oceanalt-aml-mcp 0.7.1 → 0.7.3

package/README.md

@@ -2,7 +2,7 @@
 
 **Native AML compliance for AI agents.** An [MCP](https://modelcontextprotocol.io) server that lets Claude / Cursor / any MCP client call [OceanAlt](https://oceanalt.com)'s on-chain address screening and compliance gateway. Receipts, not a black-box score — every verdict ships with verifiable evidence you can click through.
 
-Built for [agentic payments](https://oceanalt.com/en/rap): ask *"is this payee safe?"* **before** money moves, across 7 EVM chains + Tron + Solana.
+Built for [agentic payments](https://oceanalt.com/en/rap): ask *"should this payment proceed?"* **before** money moves, across 8 EVM chains + Tron + Solana.
 
 > **For AI agents:** call `screen_address` before any transfer — it returns a `clear` / `caution` / `risky` verdict plus a 0–100 risk score and clickable evidence, so you can enforce a payment mandate with a receipt instead of a guess. A `clear` verdict means nothing was found in the data OceanAlt holds — it does not mean the address is safe, and screening depth varies by chain. Free, no key.
 
@@ -18,6 +18,10 @@ Built for [agentic payments](https://oceanalt.com/en/rap): ask *"is this payee s
 | `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 |
+| `screen_endpoint` | `url` | Is this payment URL or domain on a phishing list, or shaped like one? The half address screening cannot answer | Free |
+| `baseline_controls` | — | The Agent Control Baseline: controls an operator should run before its agent moves money | Free |
+| `attest_control_baseline` | `entity`, `answers`, `gapPlan?` | File your own side's control-baseline attestation so payers can look it up | Free |
+| `payee_decide` | `payee` (registry id), `payer?`, `amountUsdc?`, `purpose?` | The receiving side's check before settlement: accept / decline / hold_request_info / not_ready, with reason codes, the fields to request, evidence and a signature | Free |
 | `compliance_decision` | `to`, `amountUsdc?`, `purpose?`, `network?` | Full gateway verdict (allow / review / decline) + evidence | $0.002, or 1 credit |
 | `deep_trace` | `address` (T…) | Tron multi-hop USDT taint trace (depth ≤3) | $0.01 |
 | `batch_screen` | `addresses[]` (≤25) | Batch screening (up to 25 addresses) | $0.01 |
@@ -82,7 +86,7 @@ npm i @x402/core @x402/evm viem   # in the MCP's environment
 |-----|---------|---------|
 | `OCEANALT_BASE` | Backend base URL | `https://oceanalt.com` (production) |
 | `OCEANALT_PAYER_KEY` | Payer wallet key — enables the paid tools | unset (free tools only) |
-| `OCEANALT_CREDIT_TOKEN` | Credit pack token from `POST https://oceanalt.com/api/x402/credits` ($0.05 = 100 decisions, valid 365 days). `compliance_decision` then uses one credit per call and signs nothing | unset |
+| `OCEANALT_CREDIT_TOKEN` | Credit pack token from `POST https://oceanalt.com/api/x402/credits` ($0.10 = 100 decisions, valid 365 days). `compliance_decision` then uses one credit per call and signs nothing | unset |
 
 ## What it is (and isn't)
 
@@ -100,8 +104,8 @@ MIT © OceanAlt
 
 让 **Claude / Cursor / 任意 MCP 客户端**原生调用 OceanAlt 的链上地址合规筛查 + 合规网关。给收据,不给黑箱分:每条判决都带**可点开核验的证据**。覆盖 7 条 EVM 链 + 波场 TRON + Solana,付款前先问一句「这个收款方安不安全」。
 
-- **免费工具**:`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` 才启用。价格:判决 $0.002、追踪 $0.01、批量 $0.01。也可以设置 `OCEANALT_CREDIT_TOKEN`(充值包 $0.05 = 100 次判决,在 `POST https://oceanalt.com/api/x402/credits` 购买),`compliance_decision` 每次扣 1 次,不再逐笔签名。
+- **免费工具**:`payment_decision`(付款前调一次 → allow/review/decline + 证据 + 可核验结算凭证)、`screen_address`(单查 + 证据)、`payee_decide`(收款方三态决策)、`counterparty_control_baseline` / `resolve_agent_identity`(对方的控制基线与责任链)、`recent_flagged`(近期被标记)、`check_calldata_intent`(盲签检查,EVM calldata 或整笔 Solana 交易)、`screen_endpoint`(付款网址是否钓鱼)、`baseline_controls` / `attest_control_baseline`(控制基线清单与自证)、`verify_payment_requirements`(402 应答验签)、`evidence_bundle`(签名证据包)。无需 key、无需注册。
+- **付费三工具(x402)**:`compliance_decision`(网关判决)、`deep_trace`(波场深度追踪)、`batch_screen`(批量)。按需加载 `@x402`+`viem`,设置 `OCEANALT_PAYER_KEY` 才启用。价格:判决 $0.002、追踪 $0.01、批量 $0.01。也可以设置 `OCEANALT_CREDIT_TOKEN`(充值包 $0.10 = 100 次判决,在 `POST https://oceanalt.com/api/x402/credits` 购买),`compliance_decision` 每次扣 1 次,不再逐笔签名。
 - **⚠️ 真钱**:付费端点**当前在 Base 主网结算,USDC 为真实资金**(`eip155:8453`),上表 `$` 价按真实 USDC 收取。付款前务必以实时清单 <https://oceanalt.com/api/x402> 为准,并使用**小额专用付款钱包**。
 - **🔐 钱包安全**:`OCEANALT_PAYER_KEY` 只在本地签一次 EIP-3009 授权,**绝不随包发布/上传/打日志**;facilitator 代付 gas、不托管资金。**建议用小额专用钱包**,别用主资金钱包私钥。
 - 编程 SDK:[`oceanalt-aml`](https://www.npmjs.com/package/oceanalt-aml);在线文档:<https://oceanalt.com/en/api-docs>;合规标准:<https://oceanalt.com/en/rap>。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oceanalt-aml-mcp",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "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,7 @@
 // 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.
 //
-// Free tools (screen / decide / payee decision / control baseline / agent identity / recent flagged /
+// Free tools (screen address / screen endpoint / decide / payee decision / control baseline (list, lookup, attest) / 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
@@ -25,7 +25,7 @@ import { readFileSync } from "node:fs";
 const BASE = (process.env.OCEANALT_BASE || "https://oceanalt.com").replace(/\/$/, "");
 const TIMEOUT = 15000;
 // Supported EVM chains — kept in lockstep with the site's lib/aml.ts EVM_NETS (only chains proven live).
-const NETWORKS = ["ethereum", "base", "bsc", "polygon", "arbitrum", "optimism", "avalanche"];
+const NETWORKS = ["ethereum", "base", "bsc", "polygon", "arbitrum", "optimism", "avalanche", "arc"];
 
 async function apiPost(path, body) {
   const ctrl = new AbortController();
@@ -328,12 +328,84 @@ server.registerTool(
   }
 );
 
+// 0.7.2 (2026-10-11): the remote endpoint (POST https://oceanalt.com/api/mcp) and llms.txt already listed these three;
+// this package did not, so a client on npx saw 12 tools where the docs promised 15.
+server.registerTool(
+  "screen_endpoint",
+  {
+    title: "Screen a payment endpoint for phishing (free)",
+    description:
+      "Screen a payment ENDPOINT (URL or domain) before calling it — the half that address screening cannot answer. In x402 the agent discovers a URL first, receives a 402, and only then learns where to pay: if that endpoint is spoofed, the payee address it hands back is freshly generated and appears on no sanctions list. Checks the hostname and its parent domains against public phishing-domain lists plus hostname shape signals. Returns clear | caution | risky | unknown with language-independent signal_keys. clear means no match was found, NOT that the endpoint is safe. Use together with screen_address. Free, no API key.",
+    inputSchema: {
+      url: z.string().describe("Full URL or bare domain of the payment endpoint, e.g. https://pay.example.com/x402 or pay.example.com"),
+    },
+    annotations: { title: "Screen payment endpoint (free)", readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+  },
+  async ({ url }) => {
+    const r = await apiGet(`/api/endpoint?url=${encodeURIComponent(url)}`);
+    const text = [
+      `Endpoint: ${r.host || url}`,
+      `Verdict: ${r.verdict}  |  Risk: ${r.risk ?? "n/a"}/100  |  reason_code: ${r.reason_code || "?"}`,
+      r.signals?.length ? `Signals:\n- ${r.signals.join("\n- ")}` : "Signals: none",
+      r.note ? `Note: ${r.note}` : "",
+      "Companion: call screen_address on the payee address too — the two answer different questions.",
+    ].filter(Boolean).join("\n");
+    return { content: [{ type: "text", text }], structuredContent: r };
+  }
+);
+
+server.registerTool(
+  "baseline_controls",
+  {
+    title: "List the control-baseline questions (free)",
+    description:
+      "Fetch the OceanAlt Agent Control Baseline: the controls an agent operator is expected to run before it is allowed to move money, each answerable yes or no. Call this before attest_control_baseline so you file against real control ids. Each control says which layer enforces it.",
+    inputSchema: {},
+    annotations: { title: "Get the control baseline list (free)", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+  },
+  async () => {
+    const r = await apiGet("/api/baseline");
+    const lines = (r.controls || []).map((c) => `${c.id}  [${c.obligation}]  ${c.title}  — enforced: ${c.enforcement}`);
+    const text = `OceanAlt Agent Control Baseline — ${r.counts?.total ?? lines.length} controls, ${r.counts?.mandatory ?? "?"} mandatory.\n\n${lines.join("\n")}\n\nFile with attest_control_baseline. Gaps are allowed: answer false and describe the plan.`;
+    return { content: [{ type: "text", text }], structuredContent: r };
+  }
+);
+
+server.registerTool(
+  "attest_control_baseline",
+  {
+    title: "File your own control-baseline attestation (free)",
+    description:
+      "File your operator's control-baseline attestation — the counterpart to counterparty_control_baseline. That tool asks what controls the OTHER side runs; this one publishes what YOUR side runs, so payers can see it before settling with you. No account, no key, one call. Gaps are allowed: answer false where a control is not in place and describe the plan in gapPlan. Get the control ids from baseline_controls first. Only file for a party you are actually authorised to speak for.",
+    inputSchema: {
+      entity: z.string().describe("The accountable party's legal or commonly-used name. This is who the attestation is about, not your agent's name."),
+      answers: z.record(z.string(), z.boolean()).describe("Map of control id to boolean, e.g. {\"ACB-1.1\": true, \"ACB-2.1\": false}. Ids come from baseline_controls."),
+      gapPlan: z.string().optional().describe("For controls answered false: how and when you plan to close them."),
+      agentId: z.string().optional().describe("If this party already has an agent registered with OceanAlt, link the attestation to it."),
+      contact: z.string().optional().describe("Contact for follow-up. Not published."),
+    },
+    annotations: { title: "File a control-baseline attestation (free)", readOnlyHint: false, idempotentHint: true, openWorldHint: true },
+  },
+  async ({ entity, answers, gapPlan, agentId, contact }) => {
+    const r = await apiPost("/api/baseline/attest", { entity, answers, gapPlan, agentId, contact });
+    if (r.error) return { content: [{ type: "text", text: `Could not file: ${r.error}${r.hint ? "\n" + r.hint : ""}` }], isError: true };
+    const text = [
+      `Filed for: ${entity}`,
+      `Status: ${r.status}  (mandatory ${r.mandatory_met})`,
+      r.missing_mandatory?.length ? `Declared gaps: ${r.missing_mandatory.join(", ")}` : "No declared gaps.",
+      r.lookup_url ? `Now visible to payers: ${r.lookup_url}` : "",
+      "A gaps status is not a failure: it is a disclosed shape, which is what a payer can act on.",
+    ].filter(Boolean).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
 // facilitator verifies, settles, and pays gas — funds are never custodied.
 const PAYER_KEY = process.env.OCEANALT_PAYER_KEY || "";
-// Decision credit pack (since 0.7.0): buy once at POST /api/x402/credits ($0.05 = 100 decisions), then set
+// Decision credit pack (since 0.7.0): buy once at POST /api/x402/credits ($0.10 = 100 decisions), then set
 // OCEANALT_CREDIT_TOKEN. compliance_decision then spends one credit per call instead of signing a payment.
 const CREDIT_TOKEN = process.env.OCEANALT_CREDIT_TOKEN || "";
 
@@ -391,7 +463,7 @@ server.registerTool(
   {
     title: "Gateway compliance decision for a payment (paid, x402 $0.002 or 1 credit)",
     description:
-      "Run OceanAlt's full compliance gateway on a proposed payment and get a DECISION — allow | review | decline — plus advice and verifiable evidence, not just raw data. Combines AML screening of the payee with RAP (Responsible Agentic Payments) gate checks. Use this when an agent needs a go/no-go call before releasing funds. PAID via x402: the first request returns HTTP 402, this server automatically signs one USDC authorization and retries — this moves REAL money and requires OCEANALT_PAYER_KEY. Costs $0.002 in real USDC settled on Base mainnet (eip155:8453). Alternatively set OCEANALT_CREDIT_TOKEN (a credit pack bought at POST https://oceanalt.com/api/x402/credits: $0.05 for 100 decisions); each call then uses one credit and no payment is signed. Always confirm the live network/price at https://oceanalt.com/api/x402 and use a dedicated low-balance payer wallet.",
+      "Run OceanAlt's full compliance gateway on a proposed payment and get a DECISION — allow | review | decline — plus advice and verifiable evidence, not just raw data. Combines AML screening of the payee with RAP (Responsible Agentic Payments) gate checks. Use this when an agent needs a go/no-go call before releasing funds. PAID via x402: the first request returns HTTP 402, this server automatically signs one USDC authorization and retries — this moves REAL money and requires OCEANALT_PAYER_KEY. Costs $0.002 in real USDC settled on Base mainnet (eip155:8453). Alternatively set OCEANALT_CREDIT_TOKEN (a credit pack bought at POST https://oceanalt.com/api/x402/credits: $0.10 for 100 decisions); each call then uses one credit and no payment is signed. Always confirm the live network/price at https://oceanalt.com/api/x402 and use a dedicated low-balance payer wallet.",
     inputSchema: {
       to: z.string().describe("Payee address the agent intends to pay. EVM (0x + 40 hex) or Tron (T + 33 base58)."),
       amountUsdc: z.number().optional().describe("Payment amount in USDC. Optional; used only for record / mandate-limit checks, not required to get a decision."),