Loanpro MCP Server

🚀 LoanPro MCP 服務器

LoanPro MCP 服務器是一個基於模型上下文協議（MCP）的服務器，它通過多種傳輸協議（HTTP、服務器發送事件（SSE）和標準輸入輸出）提供對 LoanPro 數據的只讀訪問。

🚀 快速開始

克隆項目

git clone [項目倉庫地址]

配置環境變量

複製 .env.example 文件為 .env，並配置 LoanPro API 憑證：

cp .env.example .env

編輯 .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

標準輸入輸出傳輸（適用於 MCP 客戶端，如 Claude Desktop）

go run . --transport=stdio
# 或者使用舊版標誌
go run . --stdio

✨ 主要特性

• 多傳輸協議支持：支持 HTTP、SSE 和標準輸入輸出，滿足不同場景的通信需求。
• 只讀 LoanPro 集成：安全地訪問貸款和客戶數據，保障數據的安全性。
• 全面的財務數據：提供餘額、付款、狀態和付款歷史等詳細的財務信息。
• 模塊化架構：通過專用包實現了關注點的清晰分離，提高了代碼的可維護性。
• 符合 MCP 協議：完整實現了模型上下文協議，確保與其他系統的兼容性。
• 採用 Go 語言構建：具備高性能和可靠性，能夠處理大量請求。
• 支持 CORS：允許跨域請求，方便與 Web 應用集成。

📦 安裝指南

克隆倉庫

git clone [項目倉庫地址]

配置環境變量

複製 .env.example 文件到 .env，並編輯 .env 文件，填入你的 LoanPro API 憑證：

cp .env.example .env

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 傳輸

# 獲取服務器信息
curl http://localhost:8080/

# 健康檢查
curl http://localhost:8080/health

# 列出可用工具
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# 獲取貸款詳情
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}'

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

高級用法

可根據具體業務需求，結合不同的傳輸協議和工具，實現更復雜的功能。例如，使用多個工具組合進行數據查詢和處理。

📚 詳細文檔

傳輸協議比較

可用工具

get_loan

根據貸款 ID 獲取全面的貸款信息，包括餘額、還款計劃和客戶詳細信息。 參數：

• loan_id（必需）：要獲取的貸款 ID。 返回值：包含本金餘額、還清金額、下次還款信息、逾期天數、狀態和客戶信息的完整貸款詳情。

search_loans

使用過濾器和搜索詞搜索貸款。 參數：

• search_term（可選）：用於匹配客戶姓名、顯示 ID 或標題的搜索詞。
• status（可選）：按貸款狀態過濾。
• limit（可選）：最大結果數（默認值：10）。 返回值：包含基本信息和財務數據的匹配貸款列表。

get_customer

根據客戶 ID 獲取客戶信息。 參數：

• customer_id（必需）：要獲取的客戶 ID。 返回值：包含姓名、電子郵件、電話和創建日期的客戶詳情。

search_customers

使用搜索詞搜索客戶。 參數：

• search_term（可選）：用於匹配客戶姓名、電子郵件或 SSN 的搜索詞。
• limit（可選）：最大結果數（默認值：10）。 返回值：包含聯繫信息的匹配客戶列表。

get_loan_payments

獲取貸款的還款歷史。 參數：

• loan_id（必需）：要獲取還款歷史的貸款 ID。 返回值：按時間順序排列的貸款還款列表，包含日期和金額。

構建

要構建獨立的二進制文件：

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 和標準輸入輸出傳輸進行單元測試。
• 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              # 運行完整的持續集成管道

前提條件

• Go 1.21 或更高版本。
• 可選：golangci-lint 用於代碼檢查。
• 可選：gosec 用於安全掃描。

開發工作流程

1. 修改代碼。
2. 運行測試：make test。
3. 格式化代碼：make fmt。
4. 運行代碼檢查：make lint。
5. 構建二進制文件：make build。
6. 手動測試：./loanpro-mcp-server --help。

示例響應

貸款詳情

貸款詳情:
ID: 123
顯示 ID: LN00000456
狀態: 開放
客戶: John Doe
餘額: $240000.00

搜索結果

貸款列表:
- ID: 123, 顯示 ID: LN00000456, 客戶: John Doe, 狀態: 開放, 餘額: $240000.00
- ID: 124, 顯示 ID: LN00000457, 客戶: Jane Smith, 狀態: 活躍, 餘額: $185000.00

客戶信息

客戶詳情:
ID: 456
姓名: John Doe
電子郵件: john.doe@example.com
電話: (555) 123-4567
創建時間: 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}

🔧 技術細節

• JSON-RPC 2.0 合規性：完整實現了 MCP 協議。
• 結構化日誌記錄：使用 Go 的 slog 包實現可配置的日誌級別和格式。
• 錯誤處理：將全面的錯誤信息記錄到標準錯誤輸出，並提供上下文信息。
• 日期解析：支持 LoanPro 的 Unix 時間戳格式 (/Date(1427829732)/)。
• 靈活的數據映射：能夠處理不同的 API 響應格式。
• 支持 CORS：允許跨域請求，方便與 Web 應用集成。
• 模塊化設計：在傳輸、工具和 API 層之間實現了清晰的分離。

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。