🚀 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 用于安全扫描。
开发工作流程
- 修改代码。
- 运行测试：
make test。 - 格式化代码：
make fmt。 - 运行代码检查：
make lint。 - 构建二进制文件：
make build。 - 手动测试：
./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 文件。