mcp-konduto

@codespar/mcp-konduto

适用于 Konduto 的 MCP 服务——巴西的 API 优先型欺诈防范服务。

这是 CodeSpar fraud 类别中的第二个项目，前一个是 @codespar/mcp-clearsale。Konduto 与 ClearSale 并列，是巴西商家评估的两种默认反欺诈方案之一；两者通常会并行部署，以比较评分或进行故障转移。

与 ClearSale 的定位对比

	ClearSale	Konduto
成立时间	2001 年（圣保罗）	2014 年（圣保罗）
优势	更庞大的拒付历史数据库	基于行为的设备智能
服务形式	ML 评分 + 人工审核服务	API 优先、接口更精简、面向开发者
典型搭配	巴西大型零售商的默认选择	巴西数字原生电商的默认选择

商家通常会并行运行两者：使用 Konduto 获取快速的行为信号，使用 ClearSale 分析长期拒付历史。如果一方标记为 review，另一方标记为 approved，商家就会将订单转交人工审核。

工具（18 个）

工具	用途
send_order_for_analysis	提交订单给 Konduto 进行欺诈分析。
get_order	获取订单当前的分析状态。
update_order_status	告知 Konduto 商家对订单的最终处理状态。
report_chargeback	报告订单已确认的拒付。
report_order_approved	报告商家最终批准了订单。
report_order_declined	报告商家最终拒绝了订单。
add_to_blocklist	将一个值添加到 Konduto 屏蔽名单。
query_blocklist	检查某个值当前是否在 Konduto 屏蔽名单中。
update_blocklist_entry	更新现有的屏蔽名单条目——通常用于延长或缩短过期时间（expires_at）……
remove_from_blocklist	从 Konduto 屏蔽名单中移除一个值。
add_to_allowlist	将一个值添加到 Konduto 允许名单（可信名单）。
query_allowlist	检查某个值当前是否在 Konduto 允许名单中。
update_allowlist_entry	更新现有的允许名单条目——通常用于延长或缩短过期时间。
remove_from_allowlist	从 Konduto 允许名单中移除一个值。
add_to_reviewlist	将一个值添加到 Konduto 审核名单。
query_reviewlist	检查某个值当前是否在 Konduto 审核名单中。
update_reviewlist_entry	更新现有的审核名单条目——通常用于延长或缩短过期时间，而无需移除……
remove_from_reviewlist	从 Konduto 审核名单中移除一个值。

安装

npm install @codespar/mcp-konduto@alpha

环境

KONDUTO_API_KEY="T00000..."          # private key; required
KONDUTO_BASE_URL="..."               # optional; defaults to https://api.konduto.com/v1

身份验证

HTTP Basic。API 密钥作为用户名；密码留空：

Authorization: Basic base64(KONDUTO_API_KEY + ":")

服务会处理 Base64 编码——在 KONDUTO_API_KEY 中传入原始密钥即可。

典型工作流

1. 在商家结账页面中嵌入 Konduto 的浏览器 JS SDK。它会捕获 visitor ID（行为 + 设备信号）。
2. 提交订单时，使用完整订单载荷和 visitor ID 调用 send_order_for_analysis。
3. 根据响应采取行动：approved 则发货，declined 则拦截，review 则暂缓订单以进行人工审核，或等待 ClearSale 提供第二个信号。
4. 订单生命周期结束后，使用 approved / canceled / fraud 调用 update_order_status——这些数据会用于训练 Konduto 的模型。
5. 确认发生拒付后，使用状态 fraud 调用 update_order_status。这是 Konduto 的主要 ML 反馈渠道（公开文档中没有单独的 /chargebacks 端点）。
6. 使用 add_to_blocklist 永久屏蔽在已确认欺诈事件中发现的特定邮箱 / IP / 卡 BIN + 后四位组合。

Alpha 说明

此软件包以 0.1.0-alpha.1 发布。与原始需求相比，范围如下：

• 已对照 docs.konduto.com 验证：

  • POST /orders (send_order_for_analysis)
  • POST/GET/DELETE /blacklist/{type}（黑名单系列）
  • /whitelist/{type}（允许列表）和 /greylist/{type}（审核列表），在 "APIs de Blocklist, Allowlist e Reviewlist" 下编入索引

• 标准 REST 模式，未在公开参考文档中单独编入索引（由 Konduto 官方客户端库使用）：

  • GET /orders/{id} (get_order)
  • PUT /orders/{id} (update_order_status)

• 已移除 — 未公开记录：

  • POST /disputes — docs.konduto.com 上没有争议提交端点
  • POST /cards/analyze — 未记录仅针对银行卡的预检查端点
  • GET /visitors/{visitor_id} — 订单中引用了访客 ID（visitor 字段），但不存在公开的检索端点

拒付反馈整合到 update_order_status 中，使用 status: fraud；这是 Konduto 记录的反馈渠道。

确认已移除的端点后（通过私有文档或直接 API 响应），或 Konduto 发布更广泛的公开参考文档后，将版本升级至 0.2.0。

运行

# stdio (default — for Claude Desktop, Cursor, etc)
npx @codespar/mcp-konduto

# HTTP (for server-to-server testing)
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-konduto

类别

fraud — 继 ClearSale 之后，此 CodeSpar 类别中的第二个服务。欺诈服务具有共同模式（分析 → 决策 → 反馈），有别于支付服务，因此跨服务提供商切换（ClearSale ↔ Konduto ↔ Legiti）比跨收单机构切换更直接。

企业版

需要为 Agent 支付提供治理、预算限制和审计追踪？CodeSpar Enterprise 在这些 MCP 服务之上添加策略引擎、支付路由和合规模板。

许可证

MIT