Loanpro MCP Server

🚀 LoanPro MCP Server

LoanPro MCP Serverは、HTTP、Server-Sent Events (SSE)、stdioなどの複数のトランスポートプロトコルを介して、LoanProデータへの読み取り専用アクセスを提供するModel Context Protocol (MCP) サーバーです。このサーバーにより、金融データの安全な取得や、様々なアプリケーションとの統合が可能になります。

✨ 主な機能

• 複数のトランスポートプロトコル：HTTP、SSE、stdioをサポート
• 読み取り専用のLoanPro統合：ローンと顧客データへの安全なアクセス
• 包括的な金融データ：残高、支払い、ステータス、支払い履歴
• モジュール化アーキテクチャ：専用パッケージによる明確な関心事の分離
• MCP準拠：完全なModel Context Protocolの実装
• Goで構築：高いパフォーマンスと信頼性
• CORSサポート：Web統合のためのクロスオリジンリクエスト

🔧 技術詳細

• JSON-RPC 2.0準拠：完全なMCPプロトコルの実装
• 構造化ロギング：Goのslogを使用した設定可能なログレベルと形式
• エラーハンドリング：コンテキスト付きでstderrに包括的なエラーログを記録
• 日付解析：LoanProのUnixタイムスタンプ形式 (/Date(1427829732)/) をサポート
• 柔軟なデータマッピング：異なるAPIレスポンス形式を処理
• CORSサポート：Web統合のためのクロスオリジンリクエストを有効化
• モジュール化設計：トランスポート、ツール、APIレイヤー間の明確な分離

📦 インストール

1. リポジトリをクローンします。
2. .env.example を .env にコピーし、LoanPro APIの資格情報を設定します。

   cp .env.example .env
   

3. .env を編集し、LoanPro APIの詳細を入力します。

   LOANPRO_API_URL=https://your-loanpro-instance.com/api
   LOANPRO_API_KEY=your_api_key_here
   LOANPRO_TENANT_ID=your_tenant_id_here
   PORT=8080
   
   # ロギング設定 (オプション)
   LOG_LEVEL=INFO
   LOG_FORMAT=TEXT
   

💻 使用例

基本的な使用法

HTTPトランスポート (デフォルト)

# デフォルトのHTTPトランスポート
go run .
# または明示的に指定
go run . --transport=http

サーバーは以下のエンドポイントを提供します。

• POST /mcp - MCPリクエスト
• GET / - サーバー情報
• GET /health - ヘルスチェック

SSEトランスポート (Webブラウザ用)

go run . --transport=sse

Stdioトランスポート (Claude DesktopなどのMCPクライアント用)

go run . --transport=stdio
# またはレガシーフラグを使用
go run . --stdio

高度な使用法

利用可能なツールの使用

get_loan

指定したIDのローンに関する包括的な情報を取得します。

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_loan","arguments":{"loan_id":"123"}},"id":2}'

パラメーター：

• loan_id (必須)：取得するローンのID

戻り値：元本残高、返済額、次回の支払い情報、延滞日数、ステータス、および顧客情報を含む完全なローン詳細。

search_loans

フィルターと検索条件を使用してローンを検索します。

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"search_loans","arguments":{"search_term":"John Doe"}},"id":3}'

パラメーター：

• search_term (オプション)：顧客名、表示ID、またはタイトルと一致する検索用語
• status (オプション)：ローンのステータスでフィルタリング
• limit (オプション)：最大結果数 (デフォルト: 10)

戻り値：基本情報と金融データを含む一致するローンのリスト。

get_customer

指定したIDの顧客情報を取得します。

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_customer","arguments":{"customer_id":"456"}},"id":4}'

パラメーター：

• customer_id (必須)：取得する顧客のID

戻り値：名前、メールアドレス、電話番号、および作成日を含む顧客詳細。

search_customers

検索用語を使用して顧客を検索します。

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"search_customers","arguments":{"search_term":"John Doe"}},"id":5}'

パラメーター：

• search_term (オプション)：顧客名、メールアドレス、またはSSNと一致する検索用語
• limit (オプション)：最大結果数 (デフォルト: 10)

戻り値：連絡先情報を含む一致する顧客のリスト。

get_loan_payments

指定したローンの支払い履歴を取得します。

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_loan_payments","arguments":{"loan_id":"123"}},"id":6}'

パラメーター：

• loan_id (必須)：支払い履歴を取得するローンのID

戻り値：日付と金額を含む、ローンに対する支払いの時系列リスト。

MCPクライアントの設定 (Claude Desktop)

コンパイル済みバイナリの場合：

{
  "mcpServers": {
    "loanpro": {
      "command": "/path/to/loanpro-mcp-server",
      "args": ["--transport=stdio"],
      "env": {
        "LOANPRO_API_URL": "https://your-loanpro-instance.com/api",
        "LOANPRO_API_KEY": "your_api_key",
        "LOANPRO_TENANT_ID": "your_tenant_id"
      }
    }
  }
}

Goソースの場合：

{
  "mcpServers": {
    "loanpro": {
      "command": "go",
      "args": ["run", ".", "--transport=stdio"],
      "cwd": "/path/to/loanpro-mcp-server",
      "env": {
        "LOANPRO_API_URL": "https://your-loanpro-instance.com/api",
        "LOANPRO_API_KEY": "your_api_key",
        "LOANPRO_TENANT_ID": "your_tenant_id"
      }
    }
  }
}

SSEトランスポートの使用

SSEトランスポートでサーバーを起動します。

go run . --transport=sse

SSEエンドポイントに接続します。

http://localhost:8080/sse

📚 ドキュメント

トランスポートの比較

ビルド

スタンドアロンバイナリをビルドするには、以下のコマンドを実行します。

go build -o loanpro-mcp-server .

テスト

テストの実行

提供されているMakefileを使用する場合：

make test                # テストを実行
make test-verbose        # 詳細な出力でテストを実行  
make test-coverage       # カバレッジレポート付きでテストを実行

または直接Goを使用する場合：

go test ./... -race -coverprofile=coverage.out -covermode=atomic
go test ./... -v
go test ./tools -v       # 特定のパッケージをテスト

テストカバレッジ

カバレッジレポートを生成して表示するには、以下のコマンドを実行します。

make test-coverage       # coverage.outとcoverage.htmlを生成
open coverage.html       # ブラウザで表示

# または手動で：
go test ./... -coverprofile=coverage.out
go tool cover -html=coverage.out -o coverage.html

継続的インテグレーション

このプロジェクトには、GitHub Actionsのワークフローが含まれており、自動的に以下のことを行います。

• 複数のGoバージョン (1.22.x, 1.23.x, 1.24.x) でテストを実行
• バイナリをビルドしてテスト

テスト構造

• tools/ - モックLoanProクライアントを使用したMCPツール実装の単体テスト
• transport/ - モックハンドラーを使用したHTTP、SSE、およびstdioトランスポートの単体テスト
• loanpro/ - データ型、日付解析、およびローンメソッドの単体テスト
• main_test.go - サーバーの初期化とMCPプロトコルの処理に関する統合テスト

モッキング

テストでは、外部依存関係を回避するためにモック実装を使用します。

• MockLoanProClient - LoanPro APIのレスポンスをシミュレート
• MockMCPHandler - MCPプロトコルの処理をシミュレート
• インターフェースベースの設計により、テストと依存性注入が容易になります。

開発

利用可能なMakeターゲット

make help            # 利用可能なすべてのターゲットを表示
make build           # バイナリをビルド
make test            # テストを実行
make test-coverage   # カバレッジ付きでテストを実行
make lint            # リンターを実行  
make fmt             # コードをフォーマット
make clean           # ビルドアーティファクトをクリーンアップ
make ci              # 完全なCIパイプラインを実行

前提条件

• Go 1.21以降
• オプション：コードのリント用のgolangci-lint
• オプション：セキュリティスキャン用のgosec

開発ワークフロー

1. コードに変更を加えます。
2. テストを実行します：make test
3. コードをフォーマットします：make fmt
4. リンターを実行します：make lint
5. バイナリをビルドします：make build
6. 手動でテストします：./loanpro-mcp-server --help

応答例

ローン詳細

Loan Details:
ID: 123
Display ID: LN00000456
Status: Open
Customer: John Doe
Balance: $240000.00

検索結果

Loans:
- ID: 123, Display ID: LN00000456, Customer: John Doe, Status: Open, Balance: $240000.00
- ID: 124, Display ID: LN00000457, Customer: Jane Smith, Status: Active, Balance: $185000.00

顧客情報

Customer Details:
ID: 456
Name: John Doe
Email: john.doe@example.com
Phone: (555) 123-4567
Created: 2024-01-15 10:30:22 UTC

ロギング設定

サーバーは環境変数を介して構成可能なロギングをサポートしています。

ログレベル

LOG_LEVEL 環境変数を設定して、ログの詳細度を制御します。

• DEBUG：リクエスト/レスポンスデータを含む詳細なデバッグ情報
• INFO：一般的な操作メッセージ (デフォルト)
• WARN/WARNING：警告メッセージ
• ERROR：エラーメッセージのみ

ログ形式

LOG_FORMAT 環境変数を設定して、出力形式を制御します。

• TEXT：人間が読みやすいテキスト形式 (デフォルト)
• JSON：ログ集約用の構造化JSON形式

例

# テキスト形式でデバッグレベル
LOG_LEVEL=DEBUG ./loanpro-mcp-server --transport=stdio

# JSON形式で情報レベル  
LOG_LEVEL=INFO LOG_FORMAT=JSON ./loanpro-mcp-server --transport=http

# エラーレベルのみ
LOG_LEVEL=ERROR ./loanpro-mcp-server --transport=sse

サンプル出力

テキスト形式 (デフォルト)：

time=2025-06-11T13:04:35.886-04:00 level=INFO msg="Starting MCP server" transport=http port=8080
time=2025-06-11T13:04:35.887-04:00 level=DEBUG msg="Processing HTTP request" method=tools/list id=1

JSON形式：

{"time":"2025-06-11T13:04:35.886-04:00","level":"INFO","msg":"Starting MCP server","transport":"http","port":"8080"}
{"time":"2025-06-11T13:04:35.887-04:00","level":"DEBUG","msg":"Processing HTTP request","method":"tools/list","id":1}

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。詳細については、LICENSE ファイルを参照してください。