@cmdoss/suipay-mcp 0.2.0

package/README.md

@@ -0,0 +1,103 @@
+# @cmdoss/suipay-mcp
+
+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 `@cmdoss/suipay-mcp@0.2.0` in MCP config. `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 @cmdoss/suipay-mcp@0.2.0
+```
+
+No wallet secret belongs in this command or MCP config. There is no
+Sign-In With Sui (SIWS) step.
+
+## 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 the gateway (`SUIPAY_GATEWAY_URL`) and the same network
+   the grant was created on.
+4. Call `pay`. The tool prepares unsigned `spend_account` settlement
+   bytes. If this process holds the grant's key it verifies and settles;
+   otherwise it returns the 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
+opens `{SUIPAY_CONSOLE_URL}/connect/agent?delegateAddress=0x…`.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `discover` | Search live managed-gateway resources |
+| `pay` | Fetch resource, prepare `spend_account` settlement, settle when this process holds the grant key |
+| `receipts` | List settlement receipts, optionally by challenge ID |
+| `suipay_login` | Mint or reuse the local delegate key and open the console with the public address only |
+| `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.
+
+## Client environment
+
+```bash
+SUIPAY_GATEWAY_URL=https://gateway.example
+SUIPAY_CONSOLE_URL=https://console.example
+SUIPAY_RPC_URL=https://your-testnet-rpc.example
+SUIPAY_NETWORK=testnet
+```
+
+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 @cmdoss/suipay-mcp build
+node packages/mcp/dist/bin/suipay.js
+```
+
+Binary writes status banner to stderr only. Stdout stays reserved for
+MCP protocol.
+
+Do not publish `@cmdoss/suipay-mcp` from this change.

package/dist/bin/suipay.d.ts

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

package/dist/bin/suipay.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import {
+  main
+} from "../chunk-TPW6S2K4.js";
+import "../chunk-XZQOOY66.js";
+import "../chunk-A3JIIDYT.js";
+
+// src/bin/suipay.ts
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/dist/chunk-A3JIIDYT.js

@@ -0,0 +1,161 @@
+// ../../src/protocol/rail.ts
+var SETTLEMENT_RAILS = [
+  "direct",
+  "allowance",
+  "shared_pool",
+  "spend_account",
+  "auth_capture",
+  "subscription"
+];
+function isSpendAccountRail(rail) {
+  return rail === "shared_pool" || rail === "spend_account";
+}
+var DIALECT_ORDER = ["mpp", "x402"];
+function isSettlementRail(value) {
+  return typeof value === "string" && SETTLEMENT_RAILS.includes(value);
+}
+function assertSettlementRail(value) {
+  if (!isSettlementRail(value)) {
+    throw new Error(
+      `invalid settlement rail: ${String(value)} (expected ${SETTLEMENT_RAILS.join(" | ")})`
+    );
+  }
+  return value;
+}
+function isDialect(value) {
+  return value === "mpp" || value === "x402";
+}
+function isDialectMode(value) {
+  return value === "transaction" || value === "finalized-proof";
+}
+function dialectsFromModes(modes) {
+  return DIALECT_ORDER.filter((d) => modes[d] != null);
+}
+function dialectMode(authority, dialect) {
+  const mode = authority.dialectModes[dialect];
+  if (!mode) {
+    throw new Error(
+      `${authority.rail} has no dialectMode for ${dialect} (ceiling: ${authority.supportedDialects.join(",")})`
+    );
+  }
+  return mode;
+}
+function createSettlementRailAuthority(input) {
+  assertSettlementRail(input.rail);
+  if (typeof input.packageId !== "string" || !input.packageId.trim()) {
+    throw new Error("packageId is required");
+  }
+  if (typeof input.module !== "string" || !input.module.trim()) {
+    throw new Error("module is required");
+  }
+  if (typeof input.payFunction !== "string" || !input.payFunction.trim()) {
+    throw new Error("payFunction is required");
+  }
+  const keys = Object.keys(input.dialectModes ?? {});
+  if (!keys.length) {
+    throw new Error("dialectModes must be non-empty");
+  }
+  for (const d of keys) {
+    if (!isDialect(d)) {
+      throw new Error(`unknown dialect in dialectModes: ${String(d)}`);
+    }
+    const mode = input.dialectModes[d];
+    if (!isDialectMode(mode)) {
+      throw new Error(
+        `invalid dialectMode for ${d}: ${String(mode)}`
+      );
+    }
+  }
+  const dialectModes = Object.freeze({ ...input.dialectModes });
+  const supportedDialects = Object.freeze(
+    dialectsFromModes(dialectModes)
+  );
+  const proofMode = dialectModes.mpp ?? dialectModes.x402 ?? "transaction";
+  return Object.freeze({
+    rail: input.rail,
+    packageId: input.packageId.trim(),
+    module: input.module.trim(),
+    payFunction: input.payFunction.trim(),
+    dialectModes,
+    supportedDialects,
+    proofMode
+  });
+}
+var SPEND_ACCOUNT_DEBIT_FUNCTIONS = [
+  "settle_policy_payment",
+  "settle_policy_payment_to_refund_vault",
+  "settle_open_recipient_payment",
+  "settle_open_recipient_payment_to_refund_vault"
+];
+function spendAccountDebitFunction(input) {
+  const open = input?.accessMode === "open";
+  const refundable = input?.refundable === true;
+  if (open && refundable) return "settle_open_recipient_payment_to_refund_vault";
+  if (open) return "settle_open_recipient_payment";
+  if (refundable) return "settle_policy_payment_to_refund_vault";
+  return "settle_policy_payment";
+}
+function defaultAuthorityForRail(rail, packageId, opts) {
+  switch (rail) {
+    case "spend_account":
+    case "shared_pool": {
+      const dual = opts?.x402DialectEnabled === true;
+      return createSettlementRailAuthority({
+        rail,
+        packageId,
+        module: "spend_account",
+        payFunction: spendAccountDebitFunction(),
+        dialectModes: dual ? { mpp: "finalized-proof", x402: "transaction" } : { mpp: "finalized-proof" }
+      });
+    }
+    case "allowance":
+      throw new Error(
+        "settlement rail 'allowance' is retired (ADR-0010); it is decodable but has no settlement authority"
+      );
+    case "subscription":
+      return createSettlementRailAuthority({
+        rail: "subscription",
+        packageId,
+        module: "subscription",
+        payFunction: "charge",
+        dialectModes: {
+          mpp: "transaction",
+          x402: "transaction"
+        }
+      });
+    case "direct":
+      return createSettlementRailAuthority({
+        rail: "direct",
+        packageId,
+        module: "payment",
+        payFunction: "pay",
+        dialectModes: {
+          mpp: "transaction",
+          x402: "transaction"
+        }
+      });
+    case "auth_capture":
+      return createSettlementRailAuthority({
+        rail: "auth_capture",
+        packageId,
+        module: "auth_capture",
+        payFunction: "authorize",
+        dialectModes: {
+          x402: "transaction"
+        }
+      });
+    default: {
+      const _exhaustive = rail;
+      throw new Error(`unhandled rail: ${String(_exhaustive)}`);
+    }
+  }
+}
+
+export {
+  isSpendAccountRail,
+  isSettlementRail,
+  dialectMode,
+  SPEND_ACCOUNT_DEBIT_FUNCTIONS,
+  spendAccountDebitFunction,
+  defaultAuthorityForRail
+};

package/dist/chunk-TPW6S2K4.js

@@ -0,0 +1,39 @@
+import {
+  createServer,
+  loadMcpConfig,
+  loadPaymentProfile
+} from "./chunk-XZQOOY66.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 cfg = loadMcpConfig();
+  const { profile: bootProfile, unreadable: bootProfileUnreadable } = loadBootProfile();
+  const server = createServer(cfg);
+  await server.connect(new StdioServerTransport());
+  if (bootProfileUnreadable) {
+    console.error(
+      "[suipay-mcp] credentials unreadable: run suipay_login or suipay_logout force=true \xB7 stdio ready"
+    );
+  } else if (bootProfile) {
+    console.error(
+      `[suipay-mcp] delegate ${bootProfile.creds.delegateAddress} (${bootProfile.source}) \xB7 stdio ready`
+    );
+  } else {
+    console.error(
+      "[suipay-mcp] not connected \xB7 run suipay_login \xB7 stdio ready"
+    );
+  }
+}
+
+export {
+  loadBootProfile,
+  main
+};