@cyberpay/nano-mcp 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+# @cyberpay/nano-mcp
+
+MCP Server for CyberNanoPay — 让 AI Agent 拥有零 Gas 纳米支付能力。
+
+## 为什么需要这个？
+
+传统支付方式无法满足 AI Agent 的高频微付需求：
+
+| 收费模式 | 问题 |
+|---------|------|
+| 订阅制 | Agent 为了调 3 次 API 得买一个月，用量不可预测 |
+| 积分/预付包 | 买 1000 次用了 50 次就不来了，剩余额度浪费 |
+| 信用卡按次扣 | Stripe 最低手续费 $0.30/笔，$0.001 的 API 调用根本不可能按次收 |
+| 链上直接付 | 每笔交易有 Gas 成本，高频场景（每秒几十次）不现实 |
+
+CyberNanoPay 通过 offchain Ed25519 签名 + TEE 聚合 + 链上批量结算，让单笔支付成本趋近于零，$0.0001 的微付也经济可行。
+
+**对 API 商家来说，这意味着除了订阅和积分包，多了一种之前技术上做不到的收费方式 — 真正的按次收费。**
+
+## 覆盖场景
+
+NanoPay 解锁了这些之前"链上按次付不现实"的高频场景：
+
+| 场景 | 单次价值 | 频率 | NanoPay 方案 |
+|------|---------|------|-------------|
+| LLM 推理 / 图片生成 | $0.01–$0.50 | 中频 | offchain 签名即时付，高价值场景 |
+| RPC 节点 / 链上数据查询 | $0.0001 | 每秒几十次 | TEE 链下记账，批量结算 |
+| AI Crawlers / RAG 检索 | $0.001/页 | 日均 10 万次 | x402 协议自动付费，定期结算 |
+| IoT 传感器 / 充电桩 / WiFi | $0.0001–$0.01 | 每秒/每分钟 | offchain 签名累积，定时结算 |
+| 付费文章 / 学术论文 | $0.10 | 低频 | 替代 $30 订阅，按篇付费 |
+| 短视频微付 | $0.001 | 每次观看 | 用户无感，TEE 记账 |
+| GPU 算力租用 | $0.01/秒 | 持续 | 按秒计费，批量结算 |
+| 预言机喂价 / DEX 报价 | $0.001 | 高频 | 链上生态天然打通 |
+
+## 与 @ton/mcp 的协作
+
+`@cyberpay/nano-mcp` 和 `@ton/mcp`（TON Agentic Wallets）是互补关系：
+
+```
+@ton/mcp (链上操作层)
+  ├── 充值 USDT 到 CyberGateway 合约（一次性）
+  ├── 查链上余额、交易状态
+  ├── 提款、swap、NFT 操作
+  └── 管理 Agentic Wallet
+
+@cyberpay/nano-mcp (高频微付层)
+  ├── offchain 签名支付（零 Gas，~1ms）
+  ├── TEE 验证 + 记账
+  ├── 批量结算到链上
+  └── TEE 签名收据 + Merkle 证明
+```
+
+AI Agent 的完整支付流程：
+
+```
+1. Agent 通过 @ton/mcp → 充值 USDT 到 CyberGateway（链上，一次性）
+2. Agent 通过 @cyberpay/nano-mcp → offchain 签名付费（每次 API 调用，零 Gas）
+3. TEE 聚合器 → 验签、记账、累积批次
+4. TEE → 定期批量结算到链上（bilateral netting 压缩交易数）
+5. Agent 通过 @ton/mcp → 查余额、查结算状态、需要时再充值
+```
+
+## 安装
+
+```bash
+npx @cyberpay/nano-mcp
+```
+
+## MCP 配置
+
+添加到 MCP 设置文件（`mcp.json`）：
+
+```json
+{
+  "mcpServers": {
+    "nano-pay": {
+      "command": "npx",
+      "args": ["@cyberpay/nano-mcp"],
+      "env": {
+        "NANO_TEE_URL": "https://tee.cyberpay.org"
+      }
+    }
+  }
+}
+```
+
+搭配 TON Agentic Wallet 使用（推荐）：
+
+```json
+{
+  "mcpServers": {
+    "ton": {
+      "command": "npx",
+      "args": ["-y", "@ton/mcp@alpha"]
+    },
+    "nano-pay": {
+      "command": "npx",
+      "args": ["@cyberpay/nano-mcp"],
+      "env": {
+        "NANO_TEE_URL": "https://tee.cyberpay.org"
+      }
+    }
+  }
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * CyberNanoPay MCP Server
+ *
+ * Gives AI agents gas-free nanopayment capabilities on TON.
+ * Works alongside Agentic Wallets — agent uses agentic wallet for on-chain ops,
+ * and this MCP for high-frequency micropayments.
+ *
+ * Tools:
+ *   nano_deposit       — Deposit funds (simulated or on-chain)
+ *   nano_pay           — Sign and submit a micropayment
+ *   nano_balance       — Check balance
+ *   nano_history       — View payment history
+ *   nano_receipt       — Get a TEE-signed receipt
+ *   nano_attestation   — Verify TEE attestation
+ *   nano_flush         — Trigger batch settlement (settle pending payments on-chain)
+ *   nano_withdraw      — Request withdrawal (flush unsettled → prepare for on-chain withdraw)
+ *   nano_policy        — Get or set spending policy (limits, daily cap, HITL threshold)
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+/**
+ * CyberNanoPay MCP Server
+ *
+ * Gives AI agents gas-free nanopayment capabilities on TON.
+ * Works alongside Agentic Wallets — agent uses agentic wallet for on-chain ops,
+ * and this MCP for high-frequency micropayments.
+ *
+ * Tools:
+ *   nano_deposit       — Deposit funds (simulated or on-chain)
+ *   nano_pay           — Sign and submit a micropayment
+ *   nano_balance       — Check balance
+ *   nano_history       — View payment history
+ *   nano_receipt       — Get a TEE-signed receipt
+ *   nano_attestation   — Verify TEE attestation
+ *   nano_flush         — Trigger batch settlement (settle pending payments on-chain)
+ *   nano_withdraw      — Request withdrawal (flush unsettled → prepare for on-chain withdraw)
+ *   nano_policy        — Get or set spending policy (limits, daily cap, HITL threshold)
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import nacl from "tweetnacl";
+import { createHash } from "crypto";
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+const TEE_URL = process.env.NANO_TEE_URL ?? "https://3c84244ec8585d9d81678e9f8933c2b63bbfe5cd-4030.dstack-pha-prod5.phala.network";
+const ADMIN_TOKEN = process.env.NANO_ADMIN_TOKEN ?? "";
+// ── Keypair management ──
+// Agent generates or loads a keypair for signing payments
+// Seed is persisted to ~/.cyberpay/agent-seed so address survives restarts
+const SEED_DIR = join(homedir(), ".cyberpay");
+const SEED_FILE = join(SEED_DIR, "agent-seed");
+let agentKeypair = null;
+function getOrCreateKeypair() {
+    if (agentKeypair)
+        return agentKeypair;
+    // Priority 1: env var
+    const envSeed = process.env.NANO_AGENT_SEED;
+    if (envSeed) {
+        agentKeypair = nacl.sign.keyPair.fromSeed(Buffer.from(envSeed, "hex"));
+        return agentKeypair;
+    }
+    // Priority 2: persisted seed file
+    try {
+        const saved = readFileSync(SEED_FILE, "utf-8").trim();
+        if (saved.length === 64) {
+            agentKeypair = nacl.sign.keyPair.fromSeed(Buffer.from(saved, "hex"));
+            return agentKeypair;
+        }
+    }
+    catch {
+        // File doesn't exist yet — will create below
+    }
+    // Priority 3: generate new and persist
+    const seed = nacl.randomBytes(32);
+    agentKeypair = nacl.sign.keyPair.fromSeed(seed);
+    try {
+        mkdirSync(SEED_DIR, { recursive: true });
+        writeFileSync(SEED_FILE, Buffer.from(seed).toString("hex"), { mode: 0o600 });
+    }
+    catch {
+        // Non-fatal: agent works but address changes on restart
+    }
+    return agentKeypair;
+}
+function toHex(bytes) {
+    return Buffer.from(bytes).toString("hex");
+}
+function agentAddress() {
+    const kp = getOrCreateKeypair();
+    return "0:" + toHex(kp.publicKey.slice(0, 32));
+}
+// ── Payment signing ──
+function signPayment(to, amount, nonce, validBefore) {
+    const kp = getOrCreateKeypair();
+    const prefix = Buffer.from("CyberGateway:v1:");
+    const fromHash = Buffer.from(kp.publicKey.slice(0, 32));
+    // Parse "to" address hash
+    const toClean = to.startsWith("0:") ? to.slice(2) : to;
+    const toHash = Buffer.from(toClean.padEnd(64, "0").slice(0, 64), "hex");
+    const buf = Buffer.alloc(prefix.length + 32 + 32 + 16 + 8 + 32);
+    let offset = 0;
+    prefix.copy(buf, offset);
+    offset += prefix.length;
+    fromHash.copy(buf, offset);
+    offset += 32;
+    toHash.copy(buf, offset);
+    offset += 32;
+    const amountBuf = Buffer.alloc(16);
+    let amt = amount;
+    for (let i = 15; i >= 0; i--) {
+        amountBuf[i] = Number(amt & 0xffn);
+        amt >>= 8n;
+    }
+    amountBuf.copy(buf, offset);
+    offset += 16;
+    const timeBuf = Buffer.alloc(8);
+    let ts = BigInt(validBefore);
+    for (let i = 7; i >= 0; i--) {
+        timeBuf[i] = Number(ts & 0xffn);
+        ts >>= 8n;
+    }
+    timeBuf.copy(buf, offset);
+    offset += 8;
+    Buffer.from(nonce, "hex").copy(buf, offset);
+    const hash = createHash("sha256").update(buf).digest();
+    const sig = nacl.sign.detached(new Uint8Array(hash), kp.secretKey);
+    return toHex(sig);
+}
+// ── Helpers ──
+async function teeRequest(path, options) {
+    const res = await fetch(`${TEE_URL}${path}`, options);
+    return res.json();
+}
+function adminHeaders() {
+    const h = { "Content-Type": "application/json" };
+    if (ADMIN_TOKEN)
+        h["Authorization"] = `Bearer ${ADMIN_TOKEN}`;
+    return h;
+}
+function randomHex(bytes) {
+    const buf = new Uint8Array(bytes);
+    crypto.getRandomValues(buf);
+    return toHex(buf);
+}
+// ── MCP Server ──
+const server = new McpServer({
+    name: "nano-pay",
+    version: "0.1.0",
+});
+// Tool: nano_attestation
+server.tool("nano_attestation", "Get TEE attestation report — proves the payment service runs in a secure enclave", {}, async () => {
+    const data = await teeRequest("/attestation");
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// Tool: nano_balance
+server.tool("nano_balance", "Check nanopay balance for an address", {
+    address: z.string().optional().describe("TON address to check. Defaults to agent's own address."),
+}, async ({ address }) => {
+    const addr = address ?? agentAddress();
+    const data = await teeRequest(`/balance/${addr}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// Tool: nano_deposit
+server.tool("nano_deposit", "Deposit funds into CyberNanoPay (simulated for testnet)", {
+    amount: z.string().describe("Amount in USDT units (6 decimals). e.g. '10000000' = $10"),
+    address: z.string().optional().describe("Depositor address. Defaults to agent's own address."),
+}, async ({ amount, address }) => {
+    const addr = address ?? agentAddress();
+    const kp = getOrCreateKeypair();
+    // Register pubkey first
+    await teeRequest("/register-key", {
+        method: "POST",
+        headers: adminHeaders(),
+        body: JSON.stringify({ address: addr, publicKey: toHex(kp.publicKey) }),
+    });
+    // Simulate deposit
+    const data = await teeRequest("/simulate-deposit", {
+        method: "POST",
+        headers: adminHeaders(),
+        body: JSON.stringify({ address: addr, amount }),
+    });
+    return { content: [{ type: "text", text: `Deposited ${Number(amount) / 1e6} USDT. Balance: ${Number(data.balance) / 1e6} USDT` }] };
+});
+// Tool: nano_pay
+server.tool("nano_pay", "Make a gas-free micropayment via TEE", {
+    to: z.string().describe("Recipient address"),
+    amount: z.string().describe("Amount in USDT units (6 decimals). e.g. '1000' = $0.001"),
+}, async ({ to, amount }) => {
+    const from = agentAddress();
+    const nonce = randomHex(32);
+    const validBefore = Math.floor(Date.now() / 1000) + 300;
+    const signature = signPayment(to, BigInt(amount), nonce, validBefore);
+    const data = await teeRequest("/verify", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ from, to, amount, validBefore, nonce, signature }),
+    });
+    if (data.success) {
+        return { content: [{ type: "text", text: `✓ Paid ${Number(amount) / 1e6} USDT to ${to}\nConfirmation: ${data.confirmationId}\nRemaining: ${Number(data.remainingBalance) / 1e6} USDT` }] };
+    }
+    return { content: [{ type: "text", text: `✗ Payment failed: ${data.error}` }] };
+});
+// Tool: nano_history
+server.tool("nano_history", "View recent payment history", {
+    address: z.string().optional().describe("Address to check. Defaults to agent's own."),
+    limit: z.number().optional().describe("Max results (default 10)"),
+}, async ({ address, limit }) => {
+    const addr = address ?? agentAddress();
+    const data = await teeRequest(`/history/payments/${addr}?limit=${limit ?? 10}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// Tool: nano_receipt
+server.tool("nano_receipt", "Get a TEE-signed payment receipt", {
+    confirmationId: z.string().describe("Payment confirmation ID"),
+}, async ({ confirmationId }) => {
+    const data = await teeRequest(`/receipt/${confirmationId}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// Tool: nano_stats
+server.tool("nano_stats", "Get global protocol statistics", {}, async () => {
+    const data = await teeRequest("/stats");
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// Tool: nano_flush
+server.tool("nano_flush", "Trigger batch settlement — settles pending offchain payments on-chain. Use before withdrawing.", {}, async () => {
+    const data = await teeRequest("/flush", {
+        method: "POST",
+        headers: adminHeaders(),
+    });
+    if (data.settled) {
+        return { content: [{ type: "text", text: "✓ Batch settled on-chain successfully" }] };
+    }
+    return { content: [{ type: "text", text: `Flush result: ${JSON.stringify(data)}` }] };
+});
+// Tool: nano_withdraw
+server.tool("nano_withdraw", "Request withdrawal — flushes unsettled payments for your address so funds can be withdrawn on-chain", {
+    address: z.string().optional().describe("Address to withdraw for. Defaults to agent's own."),
+}, async ({ address }) => {
+    const addr = address ?? agentAddress();
+    const data = await teeRequest("/flush-for-withdraw", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ address: addr }),
+    });
+    if (data.error) {
+        return { content: [{ type: "text", text: `✗ Withdraw failed: ${data.error}` }] };
+    }
+    const balanceUsdt = Number(data.balance) / 1e6;
+    if (data.settled) {
+        return { content: [{ type: "text", text: `✓ Settlement complete. On-chain balance: ${balanceUsdt} USDT. You can now withdraw via the CyberGateway contract (InitiateWithdraw → wait cooldown → CompleteWithdraw).` }] };
+    }
+    return { content: [{ type: "text", text: `No pending payments to settle. Current balance: ${balanceUsdt} USDT. ${data.message ?? ""}` }] };
+});
+// Tool: nano_policy_get
+server.tool("nano_policy_get", "Get spending policy for an address (limits, daily cap, HITL threshold)", {
+    address: z.string().optional().describe("Address to check. Defaults to agent's own."),
+}, async ({ address }) => {
+    const addr = address ?? agentAddress();
+    const data = await teeRequest(`/policy/${addr}`);
+    if (!data.policy) {
+        return { content: [{ type: "text", text: `No spending policy set for ${addr}` }] };
+    }
+    const p = data.policy;
+    return { content: [{ type: "text", text: `Policy for ${addr}:\n  Spending Limit: ${Number(p.spendingLimit) / 1e6} USDT per tx\n  Daily Cap: ${Number(p.dailyCap) / 1e6} USDT/day\n  HITL Threshold: ${Number(p.hitlThreshold) / 1e6} USDT (requires human approval above this)` }] };
+});
+// Tool: nano_policy_set
+server.tool("nano_policy_set", "Set spending policy — per-transaction limit, daily cap, and HITL approval threshold", {
+    address: z.string().optional().describe("Address to set policy for. Defaults to agent's own."),
+    spendingLimit: z.string().describe("Max amount per transaction in USDT units (6 decimals). e.g. '5000000' = $5"),
+    dailyCap: z.string().describe("Max daily spending in USDT units. e.g. '50000000' = $50"),
+    hitlThreshold: z.string().describe("Payments above this require human approval. e.g. '1000000' = $1"),
+}, async ({ address, spendingLimit, dailyCap, hitlThreshold }) => {
+    const addr = address ?? agentAddress();
+    const data = await teeRequest("/policy", {
+        method: "POST",
+        headers: adminHeaders(),
+        body: JSON.stringify({ address: addr, spendingLimit, dailyCap, hitlThreshold }),
+    });
+    if (data.success) {
+        return { content: [{ type: "text", text: `✓ Policy set for ${addr}:\n  Spending Limit: ${Number(spendingLimit) / 1e6} USDT/tx\n  Daily Cap: ${Number(dailyCap) / 1e6} USDT/day\n  HITL Threshold: ${Number(hitlThreshold) / 1e6} USDT` }] };
+    }
+    return { content: [{ type: "text", text: `✗ Failed: ${data.error}` }] };
+});
+// ── Start ──
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@cyberpay/nano-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for CyberNanoPay — gas-free nanopayments on TON for AI agents",
+  "type": "module",
+  "files": ["dist"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CyberpayOrg/CyberNanoPay",
+    "directory": "mcp"
+  },
+  "keywords": ["mcp", "ton", "micropayments", "nanopay", "ai-agent", "claude", "cursor"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "nano-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "tweetnacl": "^1.0.3",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5"
+  }
+}