oceanalt-aml-mcp 0.7.3 → 0.7.4

package/README.md

@@ -19,6 +19,7 @@ Built for [agentic payments](https://oceanalt.com/en/rap): ask *"should this pay
 | `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 |
+| `check_payment_request` | `from`, `headers`, `body`, `pay_to` … | An email, invoice or message asks you to pay: is the sender spoofed, are the links phishing, is the payee listed or changed, is there pressure or an instruction aimed at an AI? | 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 |
@@ -102,9 +103,9 @@ MIT © OceanAlt
 
 ## 中文
 
-让 **Claude / Cursor / 任意 MCP 客户端**原生调用 OceanAlt 的链上地址合规筛查 + 合规网关。给收据,不给黑箱分:每条判决都带**可点开核验的证据**。覆盖 7 条 EVM 链 + 波场 TRON + Solana,付款前先问一句「这个收款方安不安全」。
+让 **Claude / Cursor / 任意 MCP 客户端**原生调用 OceanAlt 的链上地址合规筛查 + 合规网关。给收据,不给黑箱分:每条判决都带**可点开核验的证据**。覆盖 8 条 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 交易)、`screen_endpoint`(付款网址是否钓鱼)、`baseline_controls` / `attest_control_baseline`(控制基线清单与自证)、`verify_payment_requirements`(402 应答验签)、`evidence_bundle`(签名证据包)。无需 key、无需注册。
+- **免费工具**:`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`(付款网址是否钓鱼)、`check_payment_request`(收到让你付钱的邮件、发票或消息时，查发件人真假、钓鱼链接、收款地址、催付话术和写给 AI 的指令)、`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、不托管资金。**建议用小额专用钱包**,别用主资金钱包私钥。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oceanalt-aml-mcp",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "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

@@ -55,7 +55,9 @@ const PKG_VERSION = (() => {
   try { return JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8")).version; }
   catch { return "0.0.0-unknown"; }
 })();
-const server = new McpServer({ name: "oceanalt-aml", version: PKG_VERSION });
+// 2026-10-19: many clients connect and never call a tool. Tell them the first step at initialize (same wording as the remote /api/mcp).
+const INSTRUCTIONS = "OceanAlt: pre-payment checks for agents. Start here: before every payment, call payment_decision (free, no key) with the payee address (to) and network; if the answer is not allow, do not pay. Try it with {\"to\":\"0xd90e2f925DA726b50C4Ed8D0Fb90Ad053324F31b\",\"network\":\"ethereum\"}, a known mixer, which returns decline. Then, as needed: screen_endpoint on the payment page URL, check_payment_request when an email, invoice or message asks you to pay, screen_address for a raw verdict. compliance_decision, deep_trace and batch_screen are paid versions (x402, real USDC); you do not need them to get started.";
+const server = new McpServer({ name: "oceanalt-aml", version: PKG_VERSION }, { instructions: INSTRUCTIONS });
 
 server.registerTool(
   "screen_address",
@@ -354,6 +356,37 @@ server.registerTool(
   }
 );
 
+server.registerTool(
+  "check_payment_request",
+  {
+    title: "Check an email, invoice or message that asks you to pay (free)",
+    description:
+      "Call this before paying because an email, invoice or chat message asked you to. Pass what you received: raw headers if you have them, the From line, subject and body (or body_html), and the payee address if you already extracted one. OceanAlt checks whether the sender is spoofed (SPF/DKIM/DMARC, a display name naming another domain, Reply-To sent elsewhere), whether the sender domain or links imitate a brand or are known phishing hosts, whether the payee is listed or differs from previous_pay_to, and whether the text pressures the reader, announces changed payment details, or carries instructions aimed at an AI. Returns allow | review | decline with findings. On decline, do not pay from this message. The text is processed in memory and not stored. Free, no API key.",
+    inputSchema: {
+      headers: z.string().optional().describe("Raw email headers, if available (needed for SPF/DKIM/DMARC)"),
+      from: z.string().optional().describe('The From line, e.g. "Acme Billing" <billing@acme.com>'),
+      reply_to: z.string().optional().describe("The Reply-To line, if any"),
+      subject: z.string().optional(),
+      body: z.string().optional().describe("Plain-text body, invoice text or chat message"),
+      body_html: z.string().optional().describe("HTML body, if available"),
+      pay_to: z.string().optional().describe("The payee address the message asks you to pay"),
+      network: z.string().optional().describe("Network of pay_to, e.g. base, ethereum, tron, solana"),
+      previous_pay_to: z.string().optional().describe("The address you paid this requester last time"),
+      expected_sender_domain: z.string().optional().describe("The domain this requester normally sends from"),
+    },
+    annotations: { title: "Check a payment request (free)", readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+  },
+  async (args) => {
+    const r = await apiPost("/api/payment-request", args);
+    const text = [
+      `Decision: ${r.decision}  |  reason_code: ${r.reason_code || "?"}`,
+      r.findings?.length ? `Findings:\n- ${r.findings.map((f) => `[${f.level}] ${f.message}`).join("\n- ")}` : "Findings: none",
+      r.advice || "",
+    ].filter(Boolean).join("\n");
+    return { content: [{ type: "text", text }], structuredContent: r };
+  }
+);
+
 server.registerTool(
   "baseline_controls",
   {
@@ -463,7 +496,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.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.",
+      "Paid version of payment_decision. Start with the free payment_decision tool; switch to this one when you need the full evidence detail and a settled per-call receipt (x402), for example in an audited payment flow. 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."),