mcp-caixa

@codespar/mcp-caixa

面向 Caixa Econômica Federal 的 MCP 服务——巴西最大的国有银行。

Caixa 覆盖了所有一级私人银行（Itaú、Bradesco、Santander、BB）都无法涉足的领域：运营联邦社会项目（PIS/PASEP、FGTS、Bolsa Família / Auxílio Brasil）、经营全国彩票（Loterias Caixa），并且是重视国有银行信誉或服务联邦转移支付受益人的商户首选银行。对于商户关注的支付场景——Pix、boleto（Cobrança / SICOB）和账户明细——Caixa 遵循所有一级银行共享的 BACEN Pix v2 标准，因此其集成方式与私营银行同行类似。

状态：alpha（0.1.0-alpha.1）

Caixa 的 Developer Portal 需要签订合同才能访问；作为国有机构，其接入流程还额外繁琐：除商业商户合同外，还需要完成供应商注册和资质认证。Pix、Cobrança（SICOB）和 Extrato 的完整 OpenAPI 规范仅对已完成接入的商户开放。此服务中的端点路径是基于以下内容推测得出的： (a) BACEN Pix v2 标准路径，(b) Caixa 公开的 SICOB / Cobrança 集成指南，以及 (c) Itaú / Bradesco / BB 通用的约定。每条未经验证的路径都在源代码中标记为 TODO(verify)。

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

工具（23）

工具	用途
get_oauth_token	为 Caixa Developer Portal 生成或返回缓存的 OAuth2 client_credentials bearer 令牌。
send_pix	从商户的 Caixa 账户发起一笔对外 Pix 付款。
create_pix_qr	创建带有 QR 码的动态 Pix 收款（cob）。
get_pix	根据 BCB endToEndId（E）检索 Pix 交易。
resolve_dict_key	在发送 Pix 前，将 DICT 密钥（CPF、CNPJ、电子邮件、电话、EVP）解析为所有者的账户数据。
refund_pix	退还之前收到的 Pix（devolução）。
create_boleto	通过 Caixa Cobrança（SICOB）签发 boleto。
get_boleto	根据 Caixa 标识符（id 或 nosso_numero）检索 boleto。
cancel_boleto	在付款前取消（baixa）尚未结清的 boleto。
get_statement	检索指定期间的账户明细交易。
get_pix_charge	根据 BCB txid 检索 Pix 即时收款（cob）。
update_pix_charge	更新（PATCH）Pix 即时收款（cob），例如。
list_pix_charges	按日期范围和可选的状态 / CPF / CNPJ 筛选并列出 Pix 即时收款（cob）。
create_pix_due_charge	创建 Pix 到期日收款（cobv），需提供付款人信息和到期日。
get_pix_due_charge	根据 BCB txid 检索 Pix 到期日收款（cobv）。
list_pix_received	按日期范围列出收到的 Pix 交易（pix recebidos）。
register_dict_key	将 DICT 密钥（CPF、CNPJ、电子邮件、电话或 EVP）注册到商户拥有的账户。
delete_dict_key	删除（注销）商户拥有的 DICT 密钥。
download_boleto_pdf	获取已签发 boleto 的渲染版 PDF。
get_account_balance	返回 Caixa 商户账户的当前余额，包括可用余额、冻结余额和透支限额……
transfer_ted	从 Caixa 商户账户向外部银行账户发起一笔对外 TED 转账。
consult_fgts	查询 FGTS 余额 / 账户明细。
pay_tribute	通过 Caixa 支付联邦税款（DARF、GPS、GRU）或其他征收单（guia de arrecadação）。

为什么选择 Caixa（而非私人银行）

• 社会项目受益人。 如果你的客户中有相当一部分人领取联邦补助款，Caixa 就是资金最先到账的地方。
• 国有银行的公信力。 与政府关系密切的商户、特许经营企业和受监管行业通常更倾向于——或被要求——在国有银行开立账户。
• 彩票 / Loterias Caixa 渠道。 Lotérica 网络中的零售商通过 Caixa 结算。
• 与私人银行使用相同的 Pix / boleto 通道。 没有技术方面的取舍——BACEN Pix v2 标准完全相同。

安装

npm install @codespar/[email protected]

环境

CAIXA_CLIENT_ID="..."       # OAuth client_id from Caixa's Developer Portal
CAIXA_CLIENT_SECRET="..."   # OAuth client_secret
CAIXA_CERT_PATH="/abs/path/to/client.crt"   # mTLS client certificate
CAIXA_KEY_PATH="/abs/path/to/client.key"    # mTLS private key
CAIXA_ENV="sandbox"                          # or "production" (default: sandbox)

身份验证

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

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

商户合同和 credenciamento 获批后，你可以从 Caixa Developer Portal 获取证书和密钥包。它们与 OAuth 凭据相互独立。

运行

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

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

注意事项

• 路径未经验证。 请查看 src/index.ts 中的 TODO(verify) 标记。已完成接入的商户应根据门户提供的 OpenAPI 规范进行验证，并提交 PR。
• 沙盒主机名仅为推测。 Caixa 会为每个商户分配一个 homologação 子域名；如果你获配的沙盒 URL 不同，请编辑 BASE_URL 进行覆盖。
• SICOB 旧版系统。 较早的 boleto 合同可能仍通过旧版 SIGCB 接口处理。create_boleto / get_boleto / cancel_boleto 工具面向 Cobrança v2；如果你的合同早于该版本，路径会有所不同。
• 接入周期。 以周而非天来规划。国有企业供应商注册是关键路径——请在开始编码之前启动注册流程。

企业版

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

许可证

MIT