@cmdoss/suipay-mcp 1.0.1

package/README.md

@@ -0,0 +1,87 @@
+# @cmdoss/suipay-mcp
+
+SuiPay MCP lets an MCP-capable agent pay MPP-gated HTTP resources from a buyer-funded Sui allowance. Buyer owns escrow. Local delegate can spend only to bound recipient, under on-chain per-payment cap.
+
+## Install
+
+Pin package version in MCP config:
+
+```bash
+claude mcp add --scope user suipay -- npx -y @cmdoss/suipay-mcp@1.0.0
+```
+
+No wallet secret belongs in this command or MCP config.
+
+## First connection
+
+1. Ask agent to call `suipay_login`.
+2. Browser opens SuiPay console.
+3. Connect buyer wallet, choose funding and per-payment cap, then approve allowance creation.
+4. Local MCP process saves delegate credentials to `~/.suipay/credentials.json` with mode `0600`.
+5. Agent can call `pay` in same MCP session.
+
+Delegate private key is generated locally. It never enters browser URL, browser page, SuiPay backend, logs, or callback payload. Only delegate public key and address leave local process. Platform sponsors create and pay gas through backend Enoki key. Owner and delegate need no SUI gas.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `discover` | Search live managed-gateway resources |
+| `pay` | Fetch resource, settle MPP challenge from allowance, present finalized proof |
+| `receipts` | List settlement receipts, optionally by challenge ID |
+| `suipay_login` | Open browser allowance provisioning flow |
+| `suipay_logout` | Remove local credentials, guarded while live escrow still holds funds |
+
+All tools remain visible before login. `pay` and `receipts` return instruction to run `suipay_login` when no credentials exist.
+
+## 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
+
+# Fallback payment terms when suipay_login receives no gatewayResourceUrl
+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 delegate address stored in credentials. Mismatch or malformed credentials stop signing. No mnemonic or ephemeral payment fallback exists.
+
+## Logout safety
+
+`suipay_logout` refuses to delete local key while live allowance still holds funds. Revoke and refund allowance in console first. `force=true` removes local credentials but does not recover escrow.
+
+## 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.
+
+## Testnet E2E
+
+See root `.env.testnet.example`, start backend with Enoki sponsorship, then run:
+
+```bash
+SUIPAY_E2E_CONFIRM=1 pnpm tsx scripts/e2e-mcp-testnet.ts
+```
+
+Script uses real testnet assets. Default funding equals one payment so successful run leaves escrow balance at zero. It verifies delegate SUI balance stays zero before and after pay.

package/dist/bin/suipay.d.ts

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

package/dist/bin/suipay.js

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

package/dist/chunk-5I6V7N3R.js

@@ -0,0 +1,67 @@
+import {
+  createSuipayMcpServer,
+  loadPaymentProfile
+} from "./chunk-772CHNGT.js";
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/config.ts
+import { SuiGrpcClient } from "@mysten/sui/grpc";
+var GRPC_URLS = {
+  mainnet: "https://fullnode.mainnet.sui.io:443",
+  testnet: "https://fullnode.testnet.sui.io:443",
+  devnet: "https://fullnode.devnet.sui.io:443",
+  localnet: "http://127.0.0.1:9000"
+};
+function loadMcpConfig(env = process.env) {
+  const network = env.SUIPAY_NETWORK ?? "testnet";
+  const gatewayUrl = env.SUIPAY_GATEWAY_URL ?? "http://localhost:4340";
+  return {
+    consoleUrl: env.SUIPAY_CONSOLE_URL ?? "http://localhost:3000",
+    gatewayUrl,
+    rpcUrl: env.SUIPAY_RPC_URL ?? GRPC_URLS[network],
+    network,
+    packageId: env.SUIPAY_PACKAGE_ID ?? "",
+    recipient: env.SUIPAY_RECIPIENT ?? "",
+    coinType: env.SUIPAY_COIN_TYPE ?? "",
+    sponsorUrl: env.SUIPAY_SPONSOR_URL ?? `${gatewayUrl.replace(/\/$/, "")}/api/sponsor`,
+    minFunded: BigInt(env.SUIPAY_MIN_FUNDED ?? "0"),
+    minMaxPerPayment: BigInt(env.SUIPAY_MIN_MAX_PER_PAYMENT ?? "0"),
+    label: env.SUIPAY_LABEL ?? "SuiPay MCP"
+  };
+}
+
+// src/index.ts
+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 = createSuipayMcpServer(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 {
+  loadMcpConfig,
+  loadBootProfile,
+  main
+};