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

高级用法

可根据具体业务需求，结合不同的传输协议和工具，实现更复杂的功能。例如，使用多个工具组合进行数据查询和处理。

📚 详细文档

传输协议比较

传输协议	使用场景	通信方式	端点
HTTP	REST 客户端、Web 应用、测试	标准 HTTP POST 请求	/mcp、/、/health
SSE	Web 浏览器、实时应用	服务器发送事件	/sse、/
标准输入输出	MCP 客户端（如 Claude Desktop）	双向标准输入输出	无

可用工具

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 文件。