Brale API MCP Server

メンテナンス終了。 このリポジトリは参照用にのみ保管されており、現在はメンテナンスや更新を行っていません。 現在メンテナンス中の SBC システムに関するセキュリティ報告については、 SBC セキュリティポリシーをご覧ください。

Brale API MCP サーバー

ステーブルコインの発行やオーケストレーション操作のための Brale API を安全にラップする、Model Context Protocol（MCP）サーバーです。

概要

この MCP サーバーを使用すると、AI アシスタントが Brale API を利用できます。この API は、ステーブルコインの発行、送金、アカウント管理、その他の金融操作に対応しています。サーバーは、Bearer トークン認証と OAuth2 クライアント認証情報認証の両方に対応し、次のツールを提供します。

• アカウント管理（アカウントとアカウントの詳細の取得）
• 送金操作（送金と送金の詳細の表示）
• アドレス管理（アドレスと残高の表示）
• 設定管理（API 認証の安全な管理）

機能

• 安全な認証：Bearer トークン認証と OAuth2 クライアント認証情報認証の両方に対応
• 型安全性：TypeScript と Zod 検証を使用して構築
• エラー処理：意味のあるエラーメッセージを含む包括的なエラー処理
• 設定管理：API 認証情報を実行時に設定
• 読み取り専用操作：データ取得のための安全な読み取り操作に特化
• 包括的なデバッグ機能：ファイルベースのログ記録、MCP Inspector との連携、本番環境に対応したビルド
• トークンの自動更新：更新機能を備えた OAuth2 トークンの自動管理

インストール

1. リポジトリをクローンします。

git clone <repository-url>
cd brale-api-mcp

2. 依存関係をインストールします。

npm install

3. Brale API の認証情報を記載した .env ファイルを作成します。

cp .env.example .env

次に .env を編集して、認証情報を追加します。

BRALE_CLIENT_ID="your_client_id_here"
BRALE_CLIENT_SECRET="your_client_secret_here"

4. プロジェクトは tsx で実行する準備が整っています（ビルド手順は不要です）。

使用方法

サーバーの実行

本番モード：

npm start
# or
npm run prod

開発モード（デバッグあり）：

npm run dev          # Auto-reload with file logging
npm run debug        # Single run with file logging
npm run inspector    # Interactive debugging with MCP Inspector

ユーティリティスクリプト：

npm run logs         # View debug logs in real-time
npm run clear-logs   # Clear the debug log file

すべてのコマンドは tsx を使用して、コンパイルせずに TypeScript を直接実行します。

デバッグ

このサーバーには、包括的なデバッグ機能が含まれています。

• ファイルベースのログ記録：開発時に mcp-debug.log へ自動的にログを記録
• MCP Inspector：ツールをテストするための対話型ウェブインターフェイス
• 本番モード：ログ記録のオーバーヘッドがないクリーンなビルド

詳しいデバッグ手順については、DEBUG.mdをご覧ください。

設定

Brale API のエンドポイントを使用する前に、認証情報を使ってサーバーを設定する必要があります。次の 2 つの方法があります。

方法 1：OAuth2 クライアント認証情報（推奨）

.env ファイルにクライアント認証情報を設定し、自動設定を使用します。

// Automatically configure using environment variables
brale_auto_configure({
  base_url: "https://api.brale.xyz" // optional, defaults to production URL
})

方法 2：手動設定

クライアント認証情報または Bearer トークンを使って、手動で設定できます。

// Configure with client credentials from environment variables
brale_configure({
  use_env_credentials: true, // default: true
  base_url: "https://api.brale.xyz" // optional
})

// Or configure with a direct bearer token
brale_configure({
  bearer_token: "your-bearer-token-here",
  base_url: "https://api.brale.xyz" // optional
})

使用可能なツール

brale_auto_configure

環境変数（BRALE_CLIENT_ID と BRALE_CLIENT_SECRET）を使用して、Brale API クライアントを自動的に設定します。

パラメーター：

• base_url（任意）：API のベース URL（デフォルトは https://api.brale.xyz）

brale_configure

認証情報を使って Brale API クライアントを設定します。Bearer トークン、または環境変数のクライアント認証情報のいずれかを使用します。

パラメーター：

• bearer_token（任意）：Brale API の Bearer トークン（.env のクライアント認証情報を使用する場合は任意）
• use_env_credentials（任意）：OAuth2 認証に環境変数の BRALE_CLIENT_ID と BRALE_CLIENT_SECRET を使用するかどうか（デフォルト：true）
• base_url（任意）：API のベース URL（デフォルトは https://api.brale.xyz）

brale_get_accounts

Brale API からすべてのアカウントを取得します。

パラメーター： なし

brale_get_account

ID を指定して、特定のアカウントを取得します。

パラメーター：

• account_id（必須）：取得するアカウントの ID

brale_get_transfers

特定のアカウントのすべての送金を取得します。

パラメーター：

• account_id（必須）：アカウントの ID

brale_get_transfer

ID を指定して特定の送金を取得します。

パラメーター：

• account_id（必須）：アカウントの ID
• transfer_id（必須）：送金の ID

brale_get_addresses

特定のアカウントに紐づくすべてのアドレスを取得します。

パラメーター：

• account_id（必須）：アカウントの ID

brale_get_address_balances

特定のアドレスの残高を取得します。

パラメーター：

• account_id（必須）：アカウントの ID
• address_id（必須）：アドレスの ID
• transfer_type（必須）：ブロックチェーン環境（例：「ethereum」、「polygon」、「base」、「solana」）
• value_type（必須）：ステーブルコインのトークンまたは通貨コード（例：「USDC」、「SBC」）

例：

brale_get_address_balances({
  account_id: "2xLccOeZcUEpSmBIhvwIMeHtes4",
  address_id: "2xLcccQBNlB2o3HzIoIQzn1Fy1Q",
  transfer_type: "base",
  value_type: "SBC"
})

brale_create_account

KYB 情報を含む新しい顧客アカウントを作成します。

パラメーター：

• business_name（必須）：事業者名
• ein（必須）：雇用者識別番号
• business_type（必須）：事業形態（例：「Corporation」、「LLC」）
• address（必須）：street_line_1、city、state、zip、country を含む事業所住所オブジェクト
• phone_number（必須）：事業用電話番号
• email（必須）：事業用メールアドレス
• website（任意）：事業用ウェブサイト
• ultimate_beneficial_owners（必須）：氏名、ssn、住所を含む UBO オブジェクトの配列
• idempotency_key（任意）：重複操作を防ぐ一意のキー（指定されない場合は自動生成）

brale_create_transfer

アカウント、アドレス、または金融機関間の新しい送金を作成します。

パラメーター：

• account_id（必須）：アカウントの ID
• amount（必須）：金額と通貨を含むオブジェクト（例：{value: "100", currency: "USD"}）
• source（必須）：value_type、transfer_type、および任意の address_id／financial_institution_id を含む送金元エンドポイント
• destination（必須）：value_type、transfer_type、および任意の address_id／financial_institution_id を含む送金先エンドポイント
• idempotency_key（任意）：重複操作を防ぐ一意のキー（指定されない場合は自動生成）

brale_get_financial_institutions

特定のアカウントに紐づくすべての金融機関を取得します。

パラメーター：

• account_id（必須）：金融機関を取得するアカウントの ID

brale_get_financial_institution

ID を指定して特定の金融機関を取得します。

パラメーター：

• account_id（必須）：アカウントの ID
• institution_id（必須）：取得する金融機関の ID

brale_create_external_financial_institution

ACH／電信送金用の新しい外部金融機関（銀行口座）を作成します。

パラメーター：

• account_id（必須）：アカウントの ID
• name（必須）：この金融機関の名前（例：「事業用当座預金口座」）
• transfer_type（必須）：対応する送金タイプの配列（例：["ach", "wire"]）
• bank_details（必須）：所有者、account_number、routing_number、name、address、account_type を含む銀行口座情報オブジェクト
• idempotency_key（任意）：重複操作を防ぐ一意のキー（指定されない場合は自動生成）

brale_create_external_address

アカウント用の新しい外部アドレス（非カストディアルウォレット）を作成します。

パラメーター：

• account_id（必須）：アカウントの ID
• name（必須）：このアドレスの名前（例：「自分の MetaMask ウォレット」）
• transfer_types（必須）：対応するブロックチェーンネットワークの配列（例：["ethereum", "polygon", "base"]）
• address（必須）：実際のブロックチェーンアドレス（例：「0x...」）
• idempotency_key（任意）：重複操作を防ぐ一意のキー（指定されない場合は自動生成）

brale_get_automations

特定のアカウントに紐づくすべての自動化設定を取得します。

パラメーター：

• account_id（必須）：自動化設定を取得するアカウントの ID

brale_get_automation

ID を指定して自動化を取得します。

パラメーター：

• account_id（必須）：アカウントの ID
• automation_id（必須）：取得する自動化の ID

brale_create_automation

自動入金アドレスまたはオンランプ用の新しい自動化を作成します。

パラメーター：

• account_id（必須）：アカウントの ID
• name（必須）：この自動化の名前（例：「Customer Onramp」）
• destination_address（必須）：address_id、value_type、transfer_type を含むオブジェクト
• idempotency_key（任意）：操作の重複を防ぐ一意のキー（指定されない場合は自動生成）

プロンプト

プロンプトの例と使用パターンについては、PROMPTS.md を参照してください。

API リファレンス

このサーバーは、以下の Brale API エンドポイントをラップします。

• GET /accounts - すべてのアカウントを取得
• GET /accounts/{id} - 特定のアカウントを取得
• GET /accounts/{account_id}/transfers - アカウントの送金を取得
• GET /accounts/{account_id}/transfers/{id} - 特定の送金を取得
• GET /accounts/{account_id}/addresses - アカウントのアドレスを取得
• GET /accounts/{account_id}/addresses/{address_id}/balance - アドレスの残高を取得（注：「balance」は単数形です）

認証

Brale API は、次の 2 つの認証方法をサポートしています。

OAuth2 クライアントクレデンシャル（推奨）

このサーバーは、クライアントクレデンシャルを使用した OAuth2 認証を自動的に処理できます。

1. Brale からクライアントクレデンシャル（Client ID と Client Secret）を取得します
2. .env ファイルに設定します。

   BRALE_CLIENT_ID="your_client_id_here"
   BRALE_CLIENT_SECRET="your_client_secret_here"
   

3. brale_auto_configure ツールを使用して認証を設定します
4. サーバーは以下を自動的に行います。
   • クレデンシャルを Base64（client_id:client_secret）にエンコードします
   • https://auth.brale.xyz/oauth2/token に POST リクエストを送信します
   • 必要に応じてトークンを更新します（5 分のバッファー付き）
   • すべての API リクエストにトークンを含めます

Bearer トークン認証

または、事前に取得した Bearer トークンを使用できます。

1. Brale から Bearer トークンを取得します（通常は OAuth2 client_credentials フローで取得します）
2. brale_configure ツールを使用して、トークンを設定した MCP サーバーを構成します
3. サーバーは、Authorization: Bearer <token> としてすべての API リクエストにトークンを含めます

エラー処理

サーバーは、包括的なエラー処理を提供します。

• 構成エラー：サーバーが構成されていない場合に明確なメッセージを表示します
• 認証エラー：無効または期限切れのトークンを適切に処理します
• 検証エラー：役立つエラーメッセージとともにパラメーターを検証します
• API エラー：Brale API のエラーレスポンスを転送します
• MCP プロトコル準拠：JSON 解析エラーを防ぐため、本番環境ではコンソール出力を行いません

セキュリティに関する考慮事項

• Bearer トークンはメモリ内にのみ保存され、永続化されません
• すべての API 通信で HTTPS を使用します
• 安全のため、サーバーが提供する操作は読み取り専用です
• 入力検証によって不正なリクエストを防ぎます
• セキュアなクレデンシャル管理により、トークンを自動的に更新します

開発

プロジェクト構成

src/
├── types.ts      # TypeScript types and Zod schemas
├── client.ts     # Brale API client implementation
├── server.ts     # MCP server implementation
└── logger.ts     # File-based logging system

開発ワークフロー

1. 開発サーバーを起動します。

   npm run dev
   

2. ログを監視します。

   npm run logs
   

3. 対話形式でテストします。

   npm run inspector
   

4. 本番ビルドをテストします。

   npm run prod
   

環境変数

開発用（.env）：

NODE_ENV=development
MCP_DEBUG=true
BRALE_CLIENT_ID="your_client_id"
BRALE_CLIENT_SECRET="your_client_secret"

本番用：

NODE_ENV=production
BRALE_CLIENT_ID="your_client_id"
BRALE_CLIENT_SECRET="your_client_secret"

デバッグ

詳細なデバッグ手順については、DEBUG.md を参照してください。

クイックデバッグコマンド

# Start with debugging
npm run dev

# View logs
npm run logs

# Interactive testing
npm run inspector

# Clear logs
npm run clear-logs

ライセンス

MIT

サポート

次の問題について：

• この MCP サーバー：このリポジトリで issue を作成してください
• Brale API：Brale サポートにお問い合わせください
• MCP プロトコル：MCP ドキュメントを参照してください

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えます
4. 該当する場合はテストを追加します
5. プルリクエストを送信します

変更履歴

v1.0.0

• 初回リリース
• 基本的なアカウント操作と送金操作
• ベアラートークン認証と OAuth2 クライアントクレデンシャル認証
• セキュリティのための読み取り専用操作
• ファイルログと MCP Inspector を備えた包括的なデバッグシステム
• 5 分前の余裕を持たせたトークンの自動更新
• マルチチェーン対応（Ethereum、Polygon、Base、Solana）
• MCP プロトコルに準拠した本番環境対応ビルド