oceanalt-aml-mcp 0.5.1 → 0.6.0

package/README.md

@@ -15,6 +15,9 @@ Built for [agentic payments](https://oceanalt.com/en/rap): ask *"is this payee s
 | `counterparty_control_baseline` | `entity?` / `agentId?` | The other question: not "is this address risky" but "how much damage could the agent on the other side do if it were talked into something". Returns their control-baseline attestation, splitting what OceanAlt enforces from what they merely claim | Free |
 | `resolve_agent_identity` | `agentId` | Chain of accountability: agent → principal → mandate → credential → wallet. Wherever it breaks is where accountability stops | Free |
 | `recent_flagged` | — | Recently flagged high-risk addresses | Free |
+| `check_calldata_intent` | `intent`, EVM: `contract`, `data` · Solana: `network:"solana"`, `transaction` (base64) | Anti blind-signing: decode what the transaction really does (ERC-20 approve dressed as a payment; SPL Approve / SetAuthority / CloseAccount) and compare with the declared payment → match / mismatch / unknown (unknown ≠ safe) | Free |
+| `verify_payment_requirements` | `payment_required` (decoded 402 JSON or raw base64), `expect?` | Was this x402 402 response tampered with in transit? Ed25519 check of the seller's signed requirements → ok / digest_mismatch / … | Free |
+| `evidence_bundle` | `address`, `network?` | One signed bundle of everything public OceanAlt can say about an address (screening + evidence + freshness, profile signals, one-hop relations, receipt stats); witness, not plaintiff | Free |
 | `compliance_decision` | `to`, `amountUsdc?`, `purpose?`, `network?` | Full gateway verdict (allow / review / decline) + evidence | $0.30 |
 | `deep_trace` | `address` (T…) | Tron multi-hop USDT taint trace (depth ≤3) | $0.20 |
 | `batch_screen` | `addresses[]` (≤25) | Batch screening | $0.10 |
@@ -96,7 +99,7 @@ MIT © OceanAlt
 
 让 **Claude / Cursor / 任意 MCP 客户端**原生调用 OceanAlt 的链上地址合规筛查 + 合规网关。给收据,不给黑箱分:每条判决都带**可点开核验的证据**。覆盖 7 条 EVM 链 + 波场 TRON + Solana,付款前先问一句「这个收款方安不安全」。
 
-- **免费三工具**:`payment_decision`(付款前调一次 → allow/review/decline + 证据 + 可核验结算凭证)、`screen_address`(单查 + 证据)、`recent_flagged`(近期被标记)。无需 key、无需注册。
+- **免费工具**:`payment_decision`(付款前调一次 → allow/review/decline + 证据 + 可核验结算凭证)、`screen_address`(单查 + 证据)、`payee_decide`(收款方三态决策)、`counterparty_control_baseline` / `resolve_agent_identity`(对方的控制基线与责任链)、`recent_flagged`(近期被标记)、`check_calldata_intent`(盲签检查,EVM calldata 或整笔 Solana 交易)、`verify_payment_requirements`(402 应答验签)、`evidence_bundle`(签名证据包)。无需 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.5.1",
+  "version": "0.6.0",
   "mcpName": "com.oceanalt/aml",
   "description": "Should this payment go to this address? MCP server for pre-settlement payment compliance: screen a payee address for OFAC sanctions, mixers, scam and hack lists and on-chain risk across 7 EVM chains, Tron and Solana — with click-through evidence, not a black-box score. Free tools need no API key. Paid x402 tools add gateway verdicts, taint tracing and batch screening.",
   "type": "module",

package/server.mjs

@@ -3,7 +3,8 @@
 // OceanAlt's on-chain address screening + compliance gateway. Ask "is this payee safe?"
 // BEFORE money moves — verdicts ship with clickable, verifiable evidence, not a black-box score.
 //
-// Two free tools (single screen + recent flagged list, no key, no signup) and three optional
+// Free tools (screen / decide / payee decision / control baseline / agent identity / recent flagged /
+// intent check incl. Solana / signed-402 verification / evidence bundle — no key, no signup) and three optional
 // x402 pay-per-call tools (gateway decision / deep taint trace / batch). The paid tools lazy-load
 // @x402 + viem and only activate when a payer wallet key (OCEANALT_PAYER_KEY) is set; if unset or
 // deps are missing they return a clear message and never crash. The facilitator verifies + settles
@@ -258,6 +259,75 @@ server.registerTool(
   }
 );
 
+// ── 0.6.0 (2026-09-14): three more free tools, mirroring the remote server at /api/mcp ──
+server.registerTool(
+  "check_calldata_intent",
+  {
+    title: "Decode a transaction and compare with declared intent (free)",
+    description:
+      "Anti blind-signing. EVM: decodes what calldata will actually do (ERC-20 transfer/approve/permit, setApprovalForAll, ownership transfer, native transfer). Solana: decodes a whole base64 transaction (SPL Token / Token-2022 Transfer, TransferChecked, Approve, SetAuthority, CloseAccount, Burn; System Transfer / Assign; ATA creation). Compares it with the payment the agent believes it is making. decision match = does what you declared; mismatch = different recipient/amount/asset, or an approval / authority change instead of a payment — do not sign; unknown = could not decode (including address-lookup-table accounts), which is NOT the same as safe. Free, no API key.",
+    inputSchema: {
+      intent: z.object({ action: z.literal("pay"), to: z.string().describe("EVM: recipient. Solana: wallet or token account."), amount: z.string().optional().describe("Base units, e.g. 10 USDC = 10000000"), asset: z.string().optional().describe("EVM: symbol/contract. Solana: mint address (checked against TransferChecked)") }).optional(),
+      contract: z.string().optional().describe("EVM only: the transaction's `to` (token contract, or the recipient for native transfers)."),
+      data: z.string().optional().describe("EVM only: 0x-prefixed hex calldata."),
+      value: z.string().optional().describe("EVM only: native value in wei."),
+      network: z.string().optional().describe("'solana' to decode a Solana transaction; EVM chain name or CAIP-2 id otherwise."),
+      transaction: z.string().optional().describe("Solana only: base64-serialized transaction or message."),
+    },
+    annotations: { title: "Check intent (free)", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+  },
+  async ({ intent, contract, data, value, network, transaction }) => {
+    if (!transaction && !data) return { content: [{ type: "text", text: "Pass data (EVM calldata) or network:'solana' + transaction (base64)." }], isError: true };
+    const r = await apiPost("/api/intent/check", transaction ? { intent, network: network || "solana", transaction } : { intent, contract, data, value, network });
+    if (r.error) return { content: [{ type: "text", text: String(r.error) }], isError: true };
+    const text = [`Decision: ${r.decision}  (${r.reason_code})`, r.en || r.note || "", r.actions ? `Actions: ${r.actions.map((a) => a.en).join(" | ")}` : (r.decoded && r.decoded.en ? `Decoded: ${r.decoded.en}` : ""), r.notes && r.notes.length ? `Notes: ${r.notes.join("; ")}` : ""].filter(Boolean).join("\n");
+    return { content: [{ type: "text", text }], structuredContent: r };
+  }
+);
+
+server.registerTool(
+  "verify_payment_requirements",
+  {
+    title: "Verify a signed x402 402 response was not tampered with (free)",
+    description:
+      "A 402 response is plaintext: any hop between seller and agent (proxy, CDN, a compromised SDK, a malicious tool) can swap the payTo address. Sellers who sign their payment requirements with OceanAlt put extensions.signedRequirements (Ed25519) inside the PAYMENT-REQUIRED header payload. Pass the decoded header JSON (or its raw base64) and, optionally, the payTo / amount you expect; get verified true/false with a reason code: ok | no_signature | digest_mismatch | signature_invalid | key_unavailable | payto_mismatch | amount_mismatch. Defends against tampering in transit, not against a compromised seller origin. Free, no API key.",
+    inputSchema: {
+      payment_required: z.any().describe("The decoded PAYMENT-REQUIRED JSON, or the raw base64 header value."),
+      keys_url: z.string().optional().describe("Where the seller publishes its keys (defaults to the keys_url inside the signature)."),
+      expect: z.object({ payTo: z.string().optional(), amount: z.string().optional() }).optional().describe("What you expect to pay; mismatches are reported."),
+    },
+    annotations: { title: "Verify signed 402 (free)", readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+  },
+  async ({ payment_required, keys_url, expect }) => {
+    const r = await apiPost("/api/x402/verify-requirements", { body: payment_required, keys_url, expect });
+    if (r.error) return { content: [{ type: "text", text: String(r.error) }], isError: true };
+    return { content: [{ type: "text", text: `Verified: ${r.verified}  (${r.reason_code})\n${r.detail || ""}${r.keys_url ? `\nKeys: ${r.keys_url} (${r.keys_fetched} fetched)` : ""}` }], structuredContent: r };
+  }
+);
+
+server.registerTool(
+  "evidence_bundle",
+  {
+    title: "Signed evidence bundle for an address (free)",
+    description:
+      "Everything OceanAlt can say about an address, in one Ed25519-signed bundle you can verify offline: screening verdict + evidence + freshness, self-built profile signals, one-hop relations to listed addresses, fulfillment receipt stats. OceanAlt is a witness, not a plaintiff: no conclusions, no attribution of persons, every item carries its source and coverage date. Everything inside is already public; there is no user data and no privileged channel — anyone may request one. Free, 10 per minute.",
+    inputSchema: {
+      address: z.string().describe("EVM (0x…), Solana / Tron (base58) or Bitcoin address."),
+      network: z.string().optional().describe("Chain, e.g. ethereum, base, solana (optional)."),
+    },
+    annotations: { title: "Evidence bundle (free)", readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+  },
+  async ({ address, network }) => {
+    const q = new URLSearchParams({ address }); if (network) q.set("network", network);
+    const r = await apiGet(`/api/evidence/bundle?${q.toString()}`);
+    const b = r.bundle || {};
+    const s = b.screening || {};
+    const asOf = s.evidence_as_of == null ? "?" : typeof s.evidence_as_of === "string" ? s.evidence_as_of : JSON.stringify(s.evidence_as_of);
+    const text = [`Subject: ${b.subject?.address}${b.subject?.network ? " on " + b.subject.network : ""}`, `Stance: ${b.stance}`, s.unavailable ? "Screening: unavailable" : `Screening: ${s.verdict} (risk ${s.risk ?? "n/a"}, blocked ${s.blocked ? "yes" : "no"}) · evidence as of ${asOf}`, `Profile signals: ${(b.profile_signals || []).length} · one-hop relations: ${(b.one_hop_relations || []).length} · verified receipts: ${b.fulfillment?.verified_receipts ?? 0}`, `Signature: ${r.signature ? "present (verify with " + (r.verify?.keys_url || "") + ")" : "missing"}`].join("\n");
+    return { content: [{ type: "text", text }], 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