mcp-bradesco

@codespar/mcp-bradesco

适用于 Bradesco 的 MCP 服务——巴西第二大私营银行（仅次于 Itaú）。

配合 @codespar/mcp-itau、@codespar/mcp-banco-inter 和 @codespar/mcp-stark-bank，可覆盖巴西主要私营银行 API 生态。Pix、boleto 和现金管理业务量可观的商户会直接接入 Bradesco，而不是通过 PSP。

状态：alpha（0.1.0-alpha.1）

Bradesco Developer Portal 需要签约才能访问——Pix、Cobrança、Arrecadação 和 Extrato 的完整 OpenAPI 规范仅对已完成接入的商户开放。本服务中的端点路径是根据以下信息推测得出的：(a) BACEN Pix v2 标准路径；(b) Bradesco 公开的集成指南；(c) Itaú / Santander / BB 通用的约定。每条未经验证的路径都在源代码中标记为 TODO(verify)。

在 0.1.x 期间请固定到确切版本；待已完成接入的商户验证后，将根据门户规范修正路径。

工具（22）

工具	用途
get_oauth_token	为 Bradesco Developer Portal 生成 OAuth2 client_credentials bearer token，或返回缓存的 token。
send_pix	从商户的 Bradesco 账户发起一笔 Pix 付款。
create_pix_qr	创建带二维码的动态 Pix 收款请求（cob）。
get_pix	根据 BCB endToEndId（E）检索 Pix 交易。
resolve_dict_key	在发送 Pix 前，将 DICT 密钥（CPF、CNPJ、电子邮件、电话、EVP）解析为所有者的账户信息。
refund_pix	退还此前收到的 Pix 款项。
create_boleto	通过 Bradesco Cobrança 开具 boleto。
get_boleto	根据 Bradesco 标识符（id 或 nosso_numero）检索 boleto。
cancel_boleto	在付款前取消未结清的 boleto。
get_statement	检索指定期间的账户交易明细。
arrecadacao_pay	通过 Bradesco Arrecadação 支付公用事业、税费或特许经营账单。
list_pix_received	列出商户在指定期间收到的 Pix 交易。
create_pix_due_charge	创建带到期日的 Pix 收款请求（cobv）——常用于分期付款和定期账单。
get_pix_due_charge	根据 txid 检索 Pix 到期收款请求（cobv）。
update_pix_due_charge	修改 Pix 到期收款请求（cobv）——付款前可调整金额、到期日、折扣或债务人信息。
register_dict_key	注册一个指向商户 Bradesco 账户的 DICT 密钥（CPF、CNPJ、电子邮件、电话或 EVP）。
delete_dict_key	删除（解除关联）一个指向商户 Bradesco 账户的 DICT 密钥。
list_boletos	按状态和开具 / 到期期间筛选，列出商户开具的 boletos。
get_boleto_pdf	以 base64 格式下载 boleto PDF。
get_account_balance	检索商户账户当前可用余额。
transfer_ted	从商户账户向受益人的银行账户转账（TED；同为 Bradesco 账户时则为 TEF）。
pay_tax_darf	通过 Bradesco Arrecadação 支付联邦税（DARF）或工会费用（GRU）。

安装

npm install @codespar/[email protected]

环境变量

BRADESCO_CLIENT_ID="..."       # OAuth client_id from Bradesco's Developer Portal
BRADESCO_CLIENT_SECRET="..."   # OAuth client_secret
BRADESCO_CERT_PATH="/abs/path/to/client.crt"   # mTLS client certificate
BRADESCO_KEY_PATH="/abs/path/to/client.key"    # mTLS private key
BRADESCO_ENV="sandbox"                          # or "production" (default: sandbox)

身份验证

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

1. OAuth2 client_credentials——服务会调用 token 端点，缓存 bearer token，直到过期前约 60 秒，并在后续调用中附加 Authorization: Bearer <token>。
2. mTLS——BACEN 对 Pix v2 强制要求双向 TLS，Bradesco 也在所有产品系列中执行此要求。服务会从你设置的路径加载客户端证书和私钥，构建 Node https.Agent，并通过它发送所有请求。

商户合同签署后，可从 Bradesco Developer Portal 获取证书和密钥包。它们与 OAuth 凭据相互独立。

基础 URL

• 生产环境：https://proxy.api.prebanco.com.br（Bradesco 的标准外部代理）
• 沙盒：https://apihom-bradescorip.bradesco.com.br（验收环境）

两个主机都标记为 TODO(verify) — Bradesco 会在某些产品系列中为每个商户配置子域名，且确切的验收环境主机可能有所不同。如果你的门户配置与此不同，请 Fork 并覆盖 BASE_URL。

运行

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

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

注意事项

• 路径尚未验证。 请查看 src/index.ts 中的 TODO(verify) 标记。已完成入驻的商户应根据门户提供的 OpenAPI 规范进行验证，并提交 PR。
• 基础 URL 是基于推测的。 请参阅上文 — 如果你的配置与此不同，请覆盖。
• Arrecadação 条码验证在此 Alpha 版本中由服务器端执行 — 暂无客户端 mod-10 / mod-11 校验。

企业版

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

许可证

MIT