关于 mcp-clearsale
mcp-clearsale 是 ClearSale 的 MCP 服务，ClearSale 是巴西主要的反欺诈服务商。它面向巴西电商场景，提供订单风险评分、设备指纹和 KYC 校验等工具，并采用分析、决策、反馈的流程。
主要功能
- 01订单欺诈分析与风险评分
- 02设备指纹会话与行为事件记录
- 03CPF、CNPJ 与地址的 KYC 校验
- 04人工审核订单与拒付通知
- 05调查案件的创建与更新
适用场景
- 01电商结账前提交订单进行欺诈分析
- 02根据评分决定放行、拦截或转人工审核
- 03将最终决策与拒付信息回传以优化模型
配置
本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。
npx -y @codespar/mcp-clearsaleCLEARSALE_API_KEY密钥ClearSale API key / bearer token used in the Authorization headerCLEARSALE_BASE_URLClearSale API base URL. Defaults to https://api.clearsale.com.br (prod). Override per contract-issued staging URL.本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。
工具
18收录的工具列表 · 更新于 2 周前
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | string | 是 | 商户侧订单 ID（必须唯一且稳定，用于关联后续状态更新和拒付） |
| ip | string | 是 | 下单时买家的 IP 地址（IPv4 或 IPv6） |
| date | string | 是 | 订单创建时间戳，采用 ISO-8601 格式（例如 2026-04-21T14:32:00Z） |
| string | 是 | 买家的电子邮件地址 | |
| items | array | 是 | 订单行项目：每项包含 sku、name、category、quantity、unit_price。 |
| payment | array | 是 | 此订单使用的一种或多种付款方式（card、boleto、pix）。银行卡详细信息必须经过令牌化处理——切勿传递原始 PAN。 |
| session_id | string | 否 | 来自 create_device_fingerprint_session 的可选设备指纹 session_id。可显著提高决策质量。 |
| total_items | number | 是 | 订单中的商品数量 |
| total_order | number | 是 | 以 BRL 计价的订单总金额（主要单位，例如 199.90） |
| customer_billing | object | 是 | 账单客户：name、document（CPF/CNPJ）、birth_date、phone 和地址字段（street、number、city、state、zip_code）。 |
| customer_shipping | object | 是 | 配送客户：name、document、phone 和地址字段。与 customer_billing 使用相同的 schema。 |
详细介绍
@codespar/mcp-clearsale
适用于 ClearSale 的 MCP 服务——巴西欺诈防范。
ClearSale 是巴西欺诈分析领域的先驱（2001 年创立于圣保罗），至今仍是巴西大多数大型电商平台默认采用的反欺诈层。这是 CodeSpar fraud 类别中的首个项目——目录中的其他服务均不提供欺诈评分。后续项目（Konduto、Legiti、Sift、Cybersource）将沿用相同的分析 → 决策 → 反馈流程。
工具（18 个）
| 工具 | 用途 |
|---|---|
send_order_for_analysis | 提交订单至 ClearSale 进行欺诈分析。 |
get_order_analysis | 获取之前提交至 ClearSale 的订单当前分析状态。 |
update_order_status | 通知 ClearSale 商家对订单的最终决定（APROVADO / CANCELADO / DEVOLVIDO）。 |
list_orders | 列出已提交至 ClearSale 的订单，可选使用筛选条件。 |
create_chargeback_notification | 向 ClearSale 报告已确认的拒付。 |
get_order_score | 仅获取订单的欺诈评分（数值范围为 0-100）。 |
create_device_fingerprint_session | 启动设备指纹会话。 |
get_device_fingerprint | 获取指纹会话中捕获的设备特征（操作系统、浏览器、时区、画布/WebGL 哈希等）。 |
resolve_manual_review | 手动处理当前处于 EM_ANALISE 状态的订单，批准或拒绝该订单。 |
get_score_by_document | 查询与巴西证件（CPF 或 CNPJ）相关的风险评分和历史信号。 |
get_score_by_contact | 查询联系标识符（电子邮件或电话）的风险评分。 |
validate_document | KYC：向 Receita Federal 核验 CPF 或 CNPJ。 |
validate_address | KYC：向 Correios 数据库核验巴西邮政地址。 |
track_behavior_event | 记录与指纹会话关联的行为信号（页面浏览、登录、注册、自定义事件）。 |
issue_challenge | 向买家发起身份验证挑战（通过短信/电子邮件发送 OTP，或提出 KBA 问题）。 |
validate_challenge_response | 验证买家对通过 issue_challenge 发起的挑战所作出的响应。 |
create_case | 创建欺诈调查案件（例如 |
update_case | 更新现有欺诈调查案件——更改状态、添加备注、重新分配或附加更多订单。 |
安装
npm install @codespar/mcp-clearsale@alpha
环境变量
CLEARSALE_API_KEY="..." # Bearer token issued by ClearSale
CLEARSALE_BASE_URL="..." # Optional. Defaults to https://api.clearsale.com.br. Override per contract-issued staging URL.
身份验证
服务端 Bearer 令牌：
Authorization: Bearer <CLEARSALE_API_KEY>
ClearSale 通过开发者门户或商业合同提供令牌。ClearSale 没有公开的沙盒环境——暂存环境 URL 按合同配置；可覆盖 CLEARSALE_BASE_URL 指向该环境。
典型流程
- 页面加载时，商家调用
create_device_fingerprint_session，并使用返回的session_token嵌入 ClearSale 的浏览器 JS。 - 结账时，商家使用相同的
session_id，以及完整的订单、付款、商品和账单/配送数据，调用send_order_for_analysis。 - 响应中会包含一个决定：
APROVADO（发货）、REPROVADO（拦截）或EM_ANALISE（轮询get_order_analysis或等待 Webhook）。 - 订单生命周期结束后，调用
update_order_status并传入商家的最终决定——这是持续提升模型质量所必需的。 - 如果之后发生拒付，调用
create_chargeback_notification，以便 ClearSale 调优其模型。
运行
# stdio (default — for Claude Desktop, Cursor, etc)
npx @codespar/mcp-clearsale
# HTTP (for server-to-server testing)
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-clearsale
类别
fraud — 此 CodeSpar 类别中的首个服务。欺诈服务采用共同的流程结构（分析 → 决策 → 反馈），与支付服务不同，因此跨提供商切换（ClearSale ↔ Konduto ↔ Legiti）比跨收单机构切换更简单。
企业版
需要为 Agent 付款设置治理、预算限制和审计跟踪？CodeSpar Enterprise 在这些 MCP 服务之上增加了策略引擎、支付路由和合规模板。
许可证
MIT
评论
一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。