mcp-sicoob

@codespar/mcp-sicoob

Sicoob 向け MCP サーバー — ブラジル最大の協同組合銀行ネットワークです。

Sicoob は、ブラジルの Pix 取引量において常に上位 4 位以内の PSP です。Sistema de Cooperativas de Crédito do Brasil は、数百の地域協同組合を統合し、Pix、Cobrança（boleto）、SPB の API を公開する単一の Developers Portal を提供しています。

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

Sicoob の Developers Portal を利用するには、協同組合への加入手続きが必要です。このサーバーのエンドポイントパスは、（a）BACEN Pix v2 の標準パス、（b）Sicoob の公開ドキュメントの抜粋、（c）Itaú／Bradesco／BB で共通する慣例に基づく推定です。未検証のパスには、ソース内で TODO(verify) のマークが付いています。

0.1.x の間は正確なバージョンに固定してください。加入済みの協同組合メンバーが検証できるようになり次第、ポータルの仕様に合わせてパスを修正します。

ツール（13）

ツール	用途
get_oauth_token	Sicoob Developers Portal 用の OAuth2 client_credentials ベアラートークンを発行するか、キャッシュ済みトークンを返します。
create_pix_cob	QR コード付きの即時 Pix 請求（cob）を作成します。
get_pix_cob	txid を指定して即時 Pix 請求を取得します。
list_pix_cob	指定期間内に加盟店が登録した即時 Pix 請求（cob）を一覧表示します。
create_pix_cobv	支払期日付きの Pix 請求（cobv）を作成します — boleto のように、支払期日以降に支払い可能な Pix で、任意の fin...
get_pix_cobv	txid を指定して支払期日付き Pix 請求（cobv）を取得します。
lookup_dict_key	Pix の送金前に、DICT キー（CPF、CNPJ、メールアドレス、電話番号、EVP）を照会して所有者の口座情報を取得します。
register_dict_key	協同組合メンバーが所有する Sicoob 口座に DICT キー（CPF、CNPJ、メールアドレス、電話番号、EVP）を登録します。
delete_dict_key	協同組合メンバーが所有する DICT キーを削除します。
create_boleto	Sicoob Cobrança 経由で boleto を発行します。
get_boleto	Sicoob 識別子（id または nosso_numero）を指定して boleto を取得します。
cancel_boleto	支払い前の未払い boleto を取り消し（baixa）します。
get_account_balance	Sicoob SPB 経由で加盟店の協同組合口座残高を照会します。

インストール

npm install @codespar/[email protected]

環境

SICOOB_CLIENT_ID="..."       # OAuth client_id from Sicoob's Developers Portal
SICOOB_CLIENT_SECRET="..."   # OAuth client_secret
SICOOB_CERT_PATH="/abs/path/to/client.crt"   # mTLS client certificate
SICOOB_KEY_PATH="/abs/path/to/client.key"    # mTLS private key
SICOOB_ENV="sandbox"                          # or "production" (default: sandbox)

認証

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

1. OAuth2 client_credentials — サーバーがトークンエンドポイントを呼び出し、有効期限の約 60 秒前までベアラーをキャッシュし、下流への呼び出しに Authorization: Bearer <token> を付加します。
2. mTLS — BACEN は Pix v2 に相互 TLS を義務付けており、Sicoob はすべての製品群でこれを適用しています。サーバーは設定されたパスからクライアント証明書と秘密鍵を読み込み、Node https.Agent を作成して、すべてのリクエストを経由させます。

証明書と鍵のバンドルは、協同組合への加入手続き後に Sicoob の Developers Portal から発行されます。OAuth 認証情報とは別のものです。

実行

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

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

注意事項

• パスは未検証です。 src/index.ts の TODO(verify) マーカーを参照してください。加入済みの協同組合は、ポータルから発行された OpenAPI 仕様に照らして検証し、PR を作成してください。
• サンドボックスのホスト名は推定です。 Sicoob は協同組合ごとにサンドボックスのサブドメインを発行します。提供されたサンドボックス URL が異なる場合は、BASE_URL を編集して上書きしてください。

エンタープライズ

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

ライセンス

MIT