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）、および extrato については、Caixa はすべての主要銀行で共通の BACEN Pix v2 標準に準拠しているため、統合の構成は民間銀行の同業他社と同様です。

ステータス：アルファ版（0.1.0-alpha.1）

Caixa の Developer Portal の利用には契約が必要であり、国有機関であることから、登録手続きもさらに煩雑です。商業加盟店契約に加えて、ベンダー登録と credenciamento が必要です。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 ベアラートークンを生成するか、キャッシュ済みのトークンを返します。
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	支払い前に未決済の boleto を取り消し（baixa）ます。
get_statement	指定期間の口座取引明細を取得します。
get_pix_charge	BCB の txid を指定して Pix の即時請求（cob）を取得します。
update_pix_charge	Pix の即時請求（cob）を更新（PATCH）します。例：
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)

認証

すべての呼び出しで、次の2つの要素が両方とも必要です。

1. OAuth2 client_credentials — サーバーはトークンエンドポイントを呼び出し、有効期限の約60秒前までベアラートークンをキャッシュして、後続の呼び出しに Authorization: Bearer <token> を付与します。
2. mTLS — BACENはPix v2で相互TLSを義務付けており、Caixaはすべてのプロダクトファミリーでこれを適用しています。サーバーは指定したパスからクライアント証明書と秘密鍵を読み込み、Nodeの https.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仕様に照らして検証し、プルリクエストを作成してください。
• サンドボックスのホストは推測です。 Caixaは加盟店ごとにhomologaçãoサブドメインを発行します。割り当てられたサンドボックスURLが異なる場合は、BASE_URL を編集して上書きしてください。
• SICOBのレガシー環境。 古いboleto契約では、レガシーのSIGCBインターフェース経由で処理される場合があります。create_boleto／get_boleto／cancel_boleto ツールはCobrança v2を対象としています。契約がそれより古い場合、パスが異なります。
• オンボーディングの所要期間。 日単位ではなく、週単位で見積もってください。国有企業のベンダー登録がクリティカルパスとなるため、コーディングを始める前に着手してください。

エンタープライズ

エージェントによる決済のガバナンス、予算上限、監査証跡が必要ですか？ CodeSpar Enterprise は、これらのMCPサーバーにポリシーエンジン、決済ルーティング、コンプライアンステンプレートを追加します。

ライセンス

MIT