@mysten-incubation/suipay-mcp 0.0.0-stage → 0.3.0-dev.0

package/README.md

@@ -1,3 +1,225 @@
-# Temporary Holding Version
+# @mysten-incubation/suipay-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.
+SuiPay MCP lets an MCP-capable agent pay MPP-gated HTTP resources from a
+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 `@mysten-incubation/suipay-mcp@0.3.0-dev.0` in MCP config for the `latest` dist-tag.
+`npx -y @mysten-incubation/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.
+
+## Install
+
+```bash
+claude mcp add --scope user suipay -- npx -y @mysten-incubation/suipay-mcp@0.3.0-dev.0
+```
+
+`@dev` installs the Railway-dev gateway/console defaults. A workspace
+checkout still defaults to localhost. `SUIPAY_GATEWAY_URL` and
+`SUIPAY_CONSOLE_URL` always override.
+
+No wallet secret belongs in this command or MCP config. There is no
+Sign-In With Sui (SIWS) step. To reuse an existing delegate seed locally,
+set `SUIPAY_MCP_KEY` (64-hex or `suiprivkey1…`) in the MCP env — never in
+the browser.
+
+## First connection
+
+First connection is a spend-account grant plus an agent-held delegate key.
+
+1. In the SuiPay console, fund a spend account and create a grant that
+   names the agent's delegate address.
+2. Persist that delegate key locally at `~/.suipay/credentials.json`
+   (mode `0600`). The process that holds this key is the only process
+   that can settle.
+3. Point MCP at a gateway. Default is Railway **suipay-dev**. Pass
+   `suipay_login({ target: "local" })` or start the binary with `--local`
+   for the laptop stack. Env/CLI fill the process default until a
+   credential is bound; after login, stored `gatewayUrl` wins. Rebind
+   with `suipay_login({ target })`.
+4. Call `pay` with `maxAmount`. On stdio the grant cap is not a default.
+   An open grant returns the payee and does not sign until a later call
+   names that recipient. When this process holds the grant's key and the
+   payee is already declared, it verifies and settles. Hosted `/mcp`
+   returns the unsigned signing request.
+
+The agent generates or is handed the delegate key. The key never enters
+a browser URL, a SuiPay backend, logs, or a callback payload. Only the
+public address leaves the local process. `suipay_login` mints or reuses
+the local version-2 key at `~/.suipay/credentials.json` (mode `0600`) and
+returns `{SUIPAY_CONSOLE_URL}/connect/agent?port=&delegateAddress=&connectState=&gateway=`
+immediately. The owner signs in the browser; the loopback callback persists
+key + gateway URL. Subsequent sessions reuse the file unless the grant is
+missing, expired, or revoked.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `discover` | Search live gateway resources. After login: `name`, `path`, `url`, `targetHash`, catalog price, and `affordable` (can this session cover one call — not authorization). Stdio `pay` still requires `maxAmount` |
+| `pay` | On stdio, `maxAmount` is required. An open grant returns the gateway payee and does not sign until `recipient` names it. Otherwise prepare `spend_account` settlement and settle when this process holds the grant key. POST `json` is the paid body. Optional stdio `file` + `fileField` fill one JSON key from a local file as canonical base64 (Walrus `contentBase64`); requires `SUIPAY_MCP_FILE_ROOT`; hosted `/mcp` refuses `file` |
+| `receipts` | List settlement receipts, optionally by challenge ID |
+| `access_context` | Report current session / delegate / policy state (no secret material) |
+| `suipay_login` | Mint or reuse the local delegate key and return a clickable console URL (does not wait for the wallet). Default target is Railway suipay-dev; pass `target: "local"` for the laptop stack |
+| `suipay_logout` | Remove local credentials |
+
+All tools remain visible before a grant is bound. `pay` and `receipts`
+return instruction to run `suipay_login` and bind a spend-account grant
+when no local credentials exist. Hosted `/mcp` never holds a spendable
+key.
+
+## Use from an agent
+
+Install once (above). After that, paying is a prompt — paste it into Claude
+(or any MCP host that has `suipay`). Do not write SDK code.
+
+```
+Pay this SuiPay resource with the suipay MCP `pay` tool. Do not write SDK code.
+
+url: https://gateway.example/v1/image/generate
+method: POST
+json: {"prompt":"a cat"}
+maxAmount: 50000
+```
+
+To store local bytes (Walrus), do not paste base64. Name the file and field.
+Set `SUIPAY_MCP_FILE_ROOT` to an absolute directory; `file` must resolve inside
+it (unset disables attach). Paths under `~/.suipay` are refused even if that
+directory falls inside the root.
+
+```
+Pay this SuiPay resource with the suipay MCP `pay` tool. Do not write SDK code.
+
+url: https://gateway.example/v1/walrus/store
+method: POST
+json: {"contentType":"text/plain"}
+file: /absolute/path/to/note.txt
+fileField: contentBase64
+maxAmount: 50000
+```
+
+`pay` uses SDK `createPayer` internally. When this process settles, a binary
+body is written once under `~/.suipay/deliveries/` and named first in the
+JSON as `savedTo` (absolute path) and `savedToUrl` (`file://`). Hosted `/mcp`
+is prepare-only and does not write a buyer file. Any MIME — image, audio,
+pdf, octet-stream. JSON stays compact (no base64 wall). An MCP `image` block
+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`. |
+| `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.
+
+| Target | Console | Gateway | How |
+| --- | --- | --- | --- |
+| `dev` (default) | `https://suipay-dev.up.railway.app` | `https://gateway-dev-ba84.up.railway.app` | no flag, or `--dev` |
+| `local` | `http://localhost:3000` | `http://127.0.0.1:4340` | `--local` / `-local`, or `suipay_login({ target: "local" })` |
+
+```bash
+# Railway suipay-dev (default)
+npx @mysten-incubation/suipay-mcp@0.3.0-dev.0
+
+# Laptop stack
+npx @mysten-incubation/suipay-mcp@0.3.0-dev.0 --local
+```
+
+`SUIPAY_MCP_TARGET=local|dev` selects the same preset. Explicit
+`SUIPAY_GATEWAY_URL` / `SUIPAY_CONSOLE_URL` fill the process default when no
+credential is bound yet. After a successful login, `credentials.json`
+`gatewayUrl` is the bound gateway: `pay` / `discover` / `suipay_login` without
+`target` stay on that binding so a leftover env cannot silently retarget spend.
+Rebind with `suipay_login({ target: "dev" | "local" })` (same key, new consent
+if that stack has no live grant).
+
+## Client environment
+
+```bash
+# Optional. Unset = Railway suipay-dev. --local uses localhost:3000 / 127.0.0.1:4340.
+SUIPAY_GATEWAY_URL=https://gateway.example
+SUIPAY_CONSOLE_URL=https://console.example
+SUIPAY_RPC_URL=https://your-testnet-rpc.example
+SUIPAY_NETWORK=testnet
+SUIPAY_MCP_TARGET=dev
+```
+
+Optional:
+
+```bash
+# Defaults to $SUIPAY_GATEWAY_URL/api/sponsor
+SUIPAY_SPONSOR_URL=https://gateway.example/api/sponsor
+
+SUIPAY_PACKAGE_ID=0x...
+SUIPAY_RECIPIENT=0x...
+SUIPAY_COIN_TYPE=0x...::usdc::USDC
+
+SUIPAY_MIN_FUNDED=5000000
+SUIPAY_MIN_MAX_PER_PAYMENT=5000000
+SUIPAY_LABEL="My agent"
+```
+
+`ENOKI_PRIVATE_API_KEY` is backend-only. Never set it in MCP config or
+local SuiPay credentials.
+
+If `SUI_SECRET_KEY` is present, it must derive to the delegate address
+stored in credentials. Mismatch or malformed credentials stop signing.
+No mnemonic or ephemeral payment fallback exists.
+
+## Logout safety
+
+`suipay_logout` removes the local credentials file. Revoke the grant in
+the console if the spend account should stop honouring this key.
+`force=true` removes local credentials even when the file is unreadable.
+
+## Build and run locally
+
+```bash
+pnpm --filter @mysten-incubation/suipay-mcp build
+node packages/mcp/dist/bin/suipay.js
+```
+
+Binary writes status banner to stderr only. Stdout stays reserved for
+MCP protocol.
+
+Publishing is the `release-npm` workflow: merge to `dev` publishes
+`@mysten-incubation/suipay-mcp@<version>-dev.N` with dist-tag `dev` (OIDC, pack gate,
+provenance). `latest` is a gated dispatch from `main` (`dry_run` default
+true). Do not `npm publish` from a laptop. See
+[`docs/guide/npm-release.md`](../../docs/guide/npm-release.md).

package/dist/bin/suipay.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/bin/suipay.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import {
+  main
+} from "../chunk-47YNZDCC.js";
+import {
+  logError
+} from "../chunk-CXM7PELK.js";
+
+// src/bin/suipay.ts
+main().catch((err) => {
+  logError({ scope: "suipay-mcp", code: "client.unexpected", withStack: true }, err);
+  process.exit(1);
+});

package/dist/chunk-47YNZDCC.js

@@ -0,0 +1,53 @@
+import {
+  createServer,
+  loadLocalSigner,
+  loadLocalSigningKeyRecord,
+  loadMcpConfig,
+  loadPaymentProfile,
+  logError
+} from "./chunk-CXM7PELK.js";
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+function loadBootProfile(load = loadPaymentProfile) {
+  try {
+    return { profile: load(), unreadable: false };
+  } catch {
+    return { profile: null, unreadable: true };
+  }
+}
+async function main() {
+  const argv = process.argv.slice(2);
+  const cfg = loadMcpConfig(process.env, argv);
+  const target = cfg.target ?? "dev";
+  const server = createServer(cfg, void 0, void 0, { transport: "stdio" });
+  await server.connect(new StdioServerTransport());
+  try {
+    const boundGateway = loadLocalSigningKeyRecord()?.gatewayUrl ?? cfg.gatewayUrl;
+    const local = loadLocalSigner();
+    if (local) {
+      process.stderr.write(`[suipay-mcp] ${target} ${boundGateway} \xB7 delegate ${local.address} \xB7 stdio ready
+`);
+    } else {
+      process.stderr.write(`[suipay-mcp] ${target} ${boundGateway} \xB7 not connected \xB7 run suipay_login \xB7 stdio ready
+`);
+    }
+  } catch (error) {
+    logError(
+      {
+        scope: "suipay-mcp",
+        code: "client.local_credentials_invalid",
+        level: "warn",
+        msg: "local credentials are unreadable; run suipay_login or suipay_logout force=true"
+      },
+      error
+    );
+    process.stderr.write(`[suipay-mcp] ${target} ${cfg.gatewayUrl} \xB7 credentials unreadable \xB7 stdio ready
+`);
+  }
+}
+
+export {
+  loadBootProfile,
+  main
+};