oceanalt-aml-mcp 0.2.1 → 0.3.0

package/README.md

@@ -10,6 +10,7 @@ Built for [agentic payments](https://oceanalt.com/en/rap): ask *"is this payee s
 
 | Tool | Input | What it does | Price |
 |------|-------|--------------|-------|
+| `payment_decision` | `to`, `amountUsdc?`, `purpose?`, `network?` | **Before your agent pays, call once** → allow / review / decline + evidence + retry + a verifiable settlement attestation | Free |
 | `screen_address` | `address` (0x… / T… / Solana), `network?` | AML verdict + risk score + verifiable evidence | Free |
 | `recent_flagged` | — | Recently flagged high-risk addresses | Free |
 | `compliance_decision` | `to`, `amountUsdc?`, `purpose?`, `network?` | Full gateway verdict (allow / review / decline) + evidence | $0.30 |
@@ -78,7 +79,7 @@ MIT © OceanAlt
 
 让 **Claude / Cursor / 任意 MCP 客户端**原生调用 OceanAlt 的链上地址合规筛查 + 合规网关。给收据,不给黑箱分:每条判决都带**可点开核验的证据**。覆盖 7 条 EVM 链 + 波场 TRON + Solana,付款前先问一句「这个收款方安不安全」。
 
-- **免费两工具**:`screen_address`(单查 + 证据)、`recent_flagged`(近期被标记)。无需 key、无需注册。
+- **免费三工具**:`payment_decision`(付款前调一次 → allow/review/decline + 证据 + 可核验结算凭证)、`screen_address`(单查 + 证据)、`recent_flagged`(近期被标记)。无需 key、无需注册。
 - **付费三工具(x402)**:`compliance_decision`(网关判决)、`deep_trace`(波场深度追踪)、`batch_screen`(批量)。按需加载 `@x402`+`viem`,设置 `OCEANALT_PAYER_KEY` 才启用。
 - **⚠️ 真钱**:付费端点**当前在 Base 主网结算,USDC 为真实资金**(`eip155:8453`),上表 `$` 价按真实 USDC 收取。付款前务必以实时清单 <https://oceanalt.com/api/x402> 为准,并使用**小额专用付款钱包**。
 - **🔐 钱包安全**:`OCEANALT_PAYER_KEY` 只在本地签一次 EIP-3009 授权,**绝不随包发布/上传/打日志**;facilitator 代付 gas、不托管资金。**建议用小额专用钱包**,别用主资金钱包私钥。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oceanalt-aml-mcp",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "mcpName": "io.github.chrisssun18-bot/oceanalt-aml",
   "description": "OceanAlt AML 的 MCP server —— 让 Claude / 任意 MCP agent 原生调用地址合规筛查(免费)+ x402 付费判决/追踪/批量。",
   "type": "module",

package/server.mjs

@@ -35,7 +35,7 @@ async function apiGet(path) {
   } finally { clearTimeout(t); }
 }
 
-const server = new McpServer({ name: "oceanalt-aml", version: "0.2.0" });
+const server = new McpServer({ name: "oceanalt-aml", version: "0.3.0" });
 
 server.registerTool(
   "screen_address",
@@ -101,6 +101,43 @@ server.registerTool(
   }
 );
 
+server.registerTool(
+  "payment_decision",
+  {
+    title: "Decide whether to pay an address before an agent pays (free)",
+    description:
+      "\"Before your agent pays, call OceanAlt once.\" Pass the payee address the agent is about to pay; get a machine-executable decision: allow | review | decline, plus verifiable evidence and retry semantics. Use this as a gate in an autonomous payment flow — if the decision is not \"allow\", do not pay. On allow/review it also returns a verifiable compliance attestation you can attach to the settlement so the payment carries proof it passed OceanAlt's decision. Free, no API key, no signup. (For the paid variant that also settles the payment on x402 rails, use compliance_decision.)",
+    inputSchema: {
+      to: z.string().describe("Payee address the agent is about to pay. EVM: 0x + 40 hex. Tron: T + 33 base58."),
+      amountUsdc: z.number().optional().describe("Amount in USDC (optional; recorded/echoed, not required for the decision)."),
+      purpose: z.string().optional().describe("Short purpose/memo for the payment (optional)."),
+      network: z.enum(NETWORKS).optional().describe("EVM chain for the payee (same set as screen_address). Optional; ignored for Tron."),
+    },
+    annotations: { title: "Payment decision (free)", readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+  },
+  async ({ to, amountUsdc, purpose, network }) => {
+    const q = new URLSearchParams({ to });
+    if (amountUsdc != null) q.set("amountUsdc", String(amountUsdc));
+    if (purpose) q.set("purpose", purpose);
+    if (network) q.set("network", network);
+    const r = await apiGet(`/api/decide?${q.toString()}`);
+    const lines = [
+      `Decision: ${r.decision}  (allow=${r.allow})`,
+      `Address: ${r.address}  |  Verdict: ${r.verdict}  |  Risk: ${r.risk == null ? "n/a" : r.risk + "/100"}`,
+      r.advice ? `Advice: ${r.advice}` : "",
+      r.retry_hint ? `Retry: ${r.retry_hint}` : "",
+      (r.signals && r.signals.length) ? `Signals:\n- ${r.signals.join("\n- ")}` : "",
+      (r.evidence && r.evidence.length)
+        ? `Evidence:\n${r.evidence.map((e) => `- ${e.label}: ${e.detail}${e.url ? ` (${e.url})` : ""}`).join("\n")}`
+        : "",
+      r.disclaimer ? `Note: ${r.disclaimer}` : "",
+      r.settlement ? `Attestation (attach to your settlement): ${r.settlement.attestation_id}  ·  verify: ${r.settlement.verify_url}` : "",
+      `Standard: ${r.standard || "https://oceanalt.com/en/rap"}`,
+    ].filter(Boolean);
+    return { content: [{ type: "text", text: lines.join("\n") }], structuredContent: r };
+  }
+);
+
 // ── Paid (x402) tools ────────────────────────────────────────────────────────
 // Require a payer wallet private key (env OCEANALT_PAYER_KEY, 0x-prefixed) plus the on-demand deps
 // @x402/core @x402/evm viem. Like the official SDK: the MCP signs one EIP-3009 authorization; the
@@ -198,4 +235,4 @@ server.registerTool(
 const transport = new StdioServerTransport();
 await server.connect(transport);
 // Once connected, don't print to stdout (stdio transport owns it); diagnostics go to stderr.
-console.error(`[oceanalt-aml-mcp] v0.2 started, base = ${BASE}, paid tools ${PAYER_KEY ? "enabled" : "disabled (OCEANALT_PAYER_KEY not set — free tools only)"}`);
+console.error(`[oceanalt-aml-mcp] v0.3 started, base = ${BASE}, paid tools ${PAYER_KEY ? "enabled" : "disabled (OCEANALT_PAYER_KEY not set — free tools only)"}`);