@cmdoss/suipay-mcp 0.2.2-dev.24 → 0.2.2-dev.25

package/README.md

@@ -5,7 +5,7 @@ buyer-funded spend account. The buyer owns the account. The agent holds the
 delegate key and can spend only under the on-chain grant (recipient bind,
 per-payment cap, budget).
 
-Pin `@cmdoss/suipay-mcp@0.2.2-dev.24` in MCP config for the `latest` dist-tag.
+Pin `@cmdoss/suipay-mcp@0.2.2-dev.25` in MCP config for the `latest` dist-tag.
 `npx -y @cmdoss/suipay-mcp@dev` tracks the `dev` prerelease line.
 `1.0.1` remains on the registry as a historical release; do not install it
 for new agents.
@@ -13,7 +13,7 @@ for new agents.
 ## Install
 
 ```bash
-claude mcp add --scope user suipay -- npx -y @cmdoss/suipay-mcp@0.2.2-dev.24
+claude mcp add --scope user suipay -- npx -y @cmdoss/suipay-mcp@0.2.2-dev.25
 ```
 
 `@dev` installs the Railway-dev gateway/console defaults. A workspace
@@ -107,6 +107,42 @@ is an extra display hint when the type is `image/*`; hosts such as Claude
 Code's TUI may not render it. Always quote `savedTo` when present. If
 `savedTo` is null, quote `saveError` and do not call `pay` again.
 
+## Tool errors — branch on `code`
+
+A tool result whose `status` is `failed` or `ambiguous` sets `isError: true`
+and puts the error model in `structuredContent`:
+
+| Field | Meaning |
+| --- | --- |
+| `status`, `paid` | As before. `paid` is `true`, `false` or `'unknown'`. |
+| `code` | Registered error code, e.g. `request.file_outside_root`. **Branch on this**, never on the text. |
+| `paymentState` | `charged`, `unknown` or `not_charged`; always agrees with `paid`. |
+| `retryable` | `true` only when a retry cannot charge twice. |
+| `nextAction` | `retry`, `retry_later`, `fix_request`, `sign_in`, `approve_access`, `add_funds`, `reconcile`, `contact_support` or `none`. |
+| `supportCode` | Always present. The gateway's when it produced the failure; otherwise minted by this MCP server and written, with the failure, to its stderr log. Find the cause in the MCP host's log by searching for it. |
+| `detail` | Developer text that states the fix. |
+| `txDigest`, `paymentId` | When known. |
+
+The text block holds the same object as JSON. When money moved or may have
+moved it **starts** with a line for the model:
+
+```
+You were charged. Do not pay again for this request.
+{ "status": "ambiguous", "paid": true, "code": "delivery.seller_unreachable", "paymentState": "charged", ... }
+```
+
+(`This payment may have gone through. Do not pay again until it is resolved.`
+when `paymentState` is `unknown`.) A result whose `status` is `ok` or
+`prepared` is never an error, including a free response that needed no
+payment.
+
+Common local codes: `auth.login_required` (run `suipay_login`),
+`request.file_outside_root` / `request.file_root_unset` (set
+`SUIPAY_MCP_FILE_ROOT`), `client.local_credentials_invalid` (log in again),
+`client.gateway_unreachable` (retry later). An unknown tool name is a JSON-RPC
+error, not a tool result; an invalid argument such as a relative `url` is a
+tool error with a `request.*` code and `nextAction: "fix_request"`.
+
 ## Targets
 
 Default is Railway **suipay-dev**. `--local` / `target: "local"` is laptop-only.
@@ -118,10 +154,10 @@ Default is Railway **suipay-dev**. `--local` / `target: "local"` is laptop-only.
 
 ```bash
 # Railway suipay-dev (default)
-npx @cmdoss/suipay-mcp@0.2.2-dev.24
+npx @cmdoss/suipay-mcp@0.2.2-dev.25
 
 # Laptop stack
-npx @cmdoss/suipay-mcp@0.2.2-dev.24 --local
+npx @cmdoss/suipay-mcp@0.2.2-dev.25 --local
 ```
 
 `SUIPAY_MCP_TARGET=local|dev` selects the same preset. Explicit

package/dist/bin/suipay.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import {
   main
-} from "../chunk-IBRMIXCG.js";
-import "../chunk-6VFKI2BY.js";
+} from "../chunk-74KH4ITB.js";
+import "../chunk-NL2IYRLH.js";
 
 // src/bin/suipay.ts
 main().catch((err) => {

package/dist/{chunk-IBRMIXCG.js → chunk-74KH4ITB.js}

@@ -4,7 +4,7 @@ import {
   loadLocalSigningKeyRecord,
   loadMcpConfig,
   loadPaymentProfile
-} from "./chunk-6VFKI2BY.js";
+} from "./chunk-NL2IYRLH.js";
 
 // src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";