mcp-santander

@codespar/mcp-santander

面向 Santander Brasil 的 MCP 服务——巴西第三大私人银行。

补齐巴西前三大私人银行组合：Itaú + Bradesco + Santander。与其他银行采用相同的 OAuth2 + mTLS 模式，但商户协议有所不同。

具有较大 Pix、boleto 和现金管理业务量的商户可直接接入 Santander，而无需通过 PSP。

状态：alpha（0.1.0-alpha.1）

Santander 的 Developer Portal 需要签约才能访问——Pix、Cobrança、Arrecadação 和 Extrato 的完整 OpenAPI 规范仅对已接入的商户开放。以下内容已根据 Santander 的公开集成指南验证：

• 生产环境主机：https://trust-open.api.santander.com.br
• 沙盒主机：https://trust-sandbox.api.santander.com.br
• OAuth2 令牌：/auth/oauth/v2/token
• Cobrança v2 基础路径：/collection_bill_management/v2/workspaces/{workspace_id}/bank_slips

其余路径（Pix、Arrecadação、Extrato）是基于以下信息做出的合理推测：(a) BACEN Pix v2 标准路径；(b) Santander 公开的营销资料；以及 (c) Itaú / Bradesco / BB 之间通用的惯例。每条未经验证的路径都在源代码中标记为 TODO(verify)。

在 0.1.x 期间请固定到精确版本；待已接入的商户能够验证后，将修正路径以符合门户规范。

工具（23）

工具	用途
get_oauth_token	为 Santander Developer Portal 创建或返回缓存的 OAuth2 client_credentials bearer token。
send_pix	从商户的 Santander 账户发起一笔 Pix 付款。
create_pix_qr	创建带二维码的动态 Pix 收款请求（cob）。
get_pix	根据 BCB 的 endToEndId（E）查询 Pix 交易。
resolve_dict_key	在发送 Pix 前，将 DICT 密钥（CPF、CNPJ、邮箱、电话、EVP）解析为所有者的账户信息。
refund_pix	退还（devolução）此前收到的 Pix。
create_boleto	通过 Santander Cobrança 开具 boleto（collection_bill_management v2）。
get_boleto	通过 Santander bill_id 查询 boleto（通过 collection_bill_management v2 的 SONDA 查询）。
cancel_boleto	在付款前取消（baixa）一张未结清的 boleto。
get_statement	查询指定期间的账户交易流水。
create_pix_cobv	创建带到期日的 Pix 收款请求（cobv——到期付款收款）。
get_pix_cob	根据 txid 查询即时 Pix 收款请求（cob）。
list_pix_cob	列出指定期间创建的即时 Pix 收款请求（cob）。
update_pix_cob	更新（PATCH）现有的即时 Pix 收款请求。
list_pix_received	列出指定期间收到的 Pix（Pix recebidos）。
register_dict_key	为商户的一个 Santander 账户注册新的 DICT 密钥。
delete_dict_key	删除（注销）此前为商户注册的 DICT 密钥。
download_boleto_pdf	获取已登记 boleto 的 PDF（副本 / segunda via）。
get_account_balance	获取 Santander 商户账户当前可用余额和冻结余额。
send_ted	从 Santander 商户账户向其他银行的账户发起 TED 转账。
transfer_internal	在两个 Santander 账户之间转账（TEF / 同一金融机构）。
create_openfinance_consent	创建 Open Finance 同意授权（受 BACEN 监管），以便访问数据或向第三方发起付款……
arrecadacao_pay	通过 Santander Arrecadação / Pagamento de Contas 支付公用事业、税费或特许经营服务账单。

安装

npm install @codespar/[email protected]

环境变量

SANTANDER_CLIENT_ID="..."       # OAuth client_id from Santander's Developer Portal
SANTANDER_CLIENT_SECRET="..."   # OAuth client_secret
SANTANDER_CERT_PATH="/abs/path/to/client.crt"   # mTLS client certificate
SANTANDER_KEY_PATH="/abs/path/to/client.key"    # mTLS private key
SANTANDER_ENV="sandbox"                         # or "production" (default: sandbox)

身份验证

每次调用都必须同时满足以下两个因素：

1. OAuth2 client_credentials — 服务向 trust-open（或 trust-sandbox）网关的 /auth/oauth/v2/token 发送 POST 请求，将令牌缓存至过期前约 60 秒，并在下游调用中附加 Authorization: Bearer <token>。
2. mTLS — BACEN 要求 Pix v2 使用双向 TLS，Santander 的 trust-open 网关则在各产品系列中强制执行此要求。服务会从你设置的路径加载客户端证书和私钥，构建 Node https.Agent，并通过它路由每个请求。

商户合同签署后，你可以从 Santander Developer Portal 获取证书和密钥包。它们与 OAuth 凭据不同。

Cobrança：工作区模型

Santander 的 Cobrança v2 采用工作区范围。注册 boletos 前，你需要通过 Developer Portal 配置一个或多个 workspace_id——每个工作区都会绑定一个 convênio、boleto/Pix 账单模式和 webhook URL。create_boleto、get_boleto 和 cancel_boleto 工具都需要 workspace_id 参数。

运行

# stdio (default)
npx @codespar/mcp-santander

# HTTP transport
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-santander

注意事项

• Pix / Arrecadação / Extrato 路径尚未验证。 请查看 src/index.ts 中的 TODO(verify) 标记。已完成接入的商户应根据门户签发的 OpenAPI 规范进行验证，并提交 PR。
• Cobrança 取消建模为带有 status: "BAIXADO" 的 PATCH；具体的 convenio 取消语义可能有所不同。
• Arrecadação 条码验证在此 alpha 版本中由服务端执行——目前尚无客户端 mod-10 / mod-11 校验。

企业版

需要为 Agent 付款设置治理、预算限制和审计跟踪？CodeSpar Enterprise 在这些 MCP 服务基础上增加了策略引擎、付款路由和合规模板。

许可证

MIT