LoanPro MCP Server

Un servidor MCP que proporciona acceso de solo lectura a los datos financieros de LoanPro.

Documentación

Servidor MCP de LoanPro

Un servidor de Model Context Protocol (MCP) que expone acceso de solo lectura a los datos de LoanPro mediante múltiples protocolos de transporte: HTTP, Server-Sent Events (SSE) y stdio.

Características

Múltiples Protocolos de Transporte: Soporte para HTTP, SSE y stdio
Integración de Solo Lectura con LoanPro: Acceso seguro a datos de préstamos y clientes
Datos Financieros Integrales: Saldos, pagos, estado e historial de pagos
Arquitectura Modular: Separación clara de responsabilidades con paquetes dedicados
Compatible con MCP: Implementación completa del Model Context Protocol
Desarrollado con Go: Alto rendimiento y fiabilidad
Soporte CORS: Solicitudes de origen cruzado para integración web

Arquitectura

El servidor está organizado en paquetes modulares para su mantenibilidad:

├── main.go              # Application entry point and transport configuration
├── loanpro/            # LoanPro API integration
│   ├── client.go       # HTTP client implementation
│   ├── types.go        # Data structures and utilities
│   ├── loans.go        # Loan operations
│   ├── customers.go    # Customer operations
│   └── payments.go     # Payment operations
├── tools/              # MCP tool implementations
│   ├── manager.go      # Tool management and execution
│   ├── types.go        # Tool interfaces and types
│   └── *.go           # Individual tool implementations
└── transport/          # Communication protocols
    ├── http.go         # Streamable HTTP transport
    ├── sse.go          # Server-Sent Events transport
    ├── stdio.go        # Stdio transport for MCP clients
    └── types.go        # Protocol types and interfaces

Configuración

Clonar el repositorio
Copiar .env.example a .env y configurar sus credenciales de la API de LoanPro:
```
cp .env.example .env
```

Editar .env con los detalles de su API de LoanPro:

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

# Logging configuration (optional)
LOG_LEVEL=INFO
LOG_FORMAT=TEXT

Ejecución

Transporte HTTP (Predeterminado)

# Default HTTP transport
go run .
# or explicitly
go run . --transport=http

El servidor proporcionará los siguientes endpoints:

POST /mcp - Solicitudes MCP
GET / - Información del servidor
GET /health - Verificación de estado

Transporte SSE (para navegadores web)

go run . --transport=sse

Transporte Stdio (para clientes MCP como Claude Desktop)

go run . --transport=stdio
# or using the legacy flag
go run . --stdio

Comparación de Transportes

Transporte	Caso de Uso	Comunicación	Endpoints
HTTP	Clientes REST, aplicaciones web, pruebas	POST HTTP estándar	`/mcp`, `/`, `/health`
SSE	Navegadores web, aplicaciones en tiempo real	Eventos enviados por el servidor	`/sse`, `/`
Stdio	Clientes MCP (Claude Desktop)	stdin/stdout bidireccional	N/A

Herramientas Disponibles

get_loan

Recupera información integral del préstamo por ID, incluyendo saldos, calendarios de pago y detalles del cliente.

Parámetros:

loan_id (obligatorio): El ID del préstamo a recuperar

Devuelve: Detalles completos del préstamo con saldo principal, monto de liquidación, información del próximo pago, días de atraso, estado e información del cliente.

search_loans

Busca préstamos con filtros y términos de búsqueda.

Parámetros:

search_term (opcional): Término de búsqueda para coincidir con nombre del cliente, ID de visualización o título
status (opcional): Filtrar por estado del préstamo
limit (opcional): Número máximo de resultados (predeterminado: 10)

Devuelve: Lista de préstamos coincidentes con información básica y datos financieros.

get_customer

Recupera información del cliente por ID.

Parámetros:

customer_id (obligatorio): El ID del cliente a recuperar

Devuelve: Detalles del cliente incluyendo nombre, correo electrónico, teléfono y fecha de creación.

search_customers

Busca clientes con un término de búsqueda.

Parámetros:

search_term (opcional): Término de búsqueda para coincidir con nombres de clientes, correo electrónico o SSN
limit (opcional): Número máximo de resultados (predeterminado: 10)

Devuelve: Lista de clientes coincidentes con información de contacto.

get_loan_payments

Obtiene el historial de pagos de un préstamo.

Parámetros:

loan_id (obligatorio): El ID del préstamo para obtener el historial de pagos

Devuelve: Lista cronológica de pagos realizados en el préstamo con fechas, montos, IDs de pago y estado (Activo/Inactivo).

get_loan_transactions

Obtiene el historial detallado de transacciones de un préstamo, incluyendo pagos, cargos, créditos y ajustes.

Parámetros:

loan_id (obligatorio): El ID del préstamo para obtener el historial de transacciones

Devuelve: Historial integral de transacciones que incluye:

Tipo de transacción (pago, cargo, crédito, ajuste, etc.)
Monto de la transacción, fecha, ID y estado
Desglose de aplicación del pago (principal, intereses, tarifas, depósito en garantía)
Título y descripción de la transacción
Rastro de auditoría completo de todas las actividades del préstamo

Ejemplos de Uso

Transporte HTTP

# Get server info
curl http://localhost:8080/

# Health check
curl http://localhost:8080/health

# List available tools
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Get loan details
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}'

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

Configuración del Cliente MCP (Claude Desktop)

Para binario compilado:

{
  "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"
      }
    }
  }
}

Para código fuente 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"
      }
    }
  }
}

Transporte SSE

Iniciar el servidor con transporte SSE:

go run . --transport=sse

Conectarse al endpoint SSE:

http://localhost:8080/sse

Compilación

Para compilar un binario independiente:

go build -o loanpro-mcp-server .

Pruebas

Ejecutar Pruebas

Usando el Makefile proporcionado:

make test                # Run tests
make test-verbose        # Run tests with verbose output  
make test-coverage       # Run tests with coverage report

O directamente con Go:

go test ./... -race -coverprofile=coverage.out -covermode=atomic
go test ./... -v
go test ./tools -v       # Test specific package

Cobertura de Pruebas

Generar y ver el informe de cobertura:

make test-coverage       # Generates coverage.out and coverage.html
open coverage.html       # View in browser

# Or manually:
go test ./... -coverprofile=coverage.out
go tool cover -html=coverage.out -o coverage.html

Integración Continua

El proyecto incluye flujos de trabajo de GitHub Actions que automáticamente:

Ejecutan pruebas en múltiples versiones de Go (1.22.x, 1.23.x, 1.24.x)
Compilan y prueban el binario

Estructura de Pruebas

tools/ - Pruebas unitarias para implementaciones de herramientas MCP con cliente LoanPro simulado
transport/ - Pruebas unitarias para transportes HTTP, SSE y stdio con manejadores simulados
loanpro/ - Pruebas unitarias para tipos de datos, análisis de fechas y métodos de préstamo
main_test.go - Pruebas de integración para inicialización del servidor y manejo del protocolo MCP

Simulación

Las pruebas utilizan implementaciones simuladas para evitar dependencias externas:

MockLoanProClient - Simula respuestas de la API de LoanPro
MockMCPHandler - Simula el manejo del protocolo MCP
El diseño basado en interfaces permite pruebas fáciles e inyección de dependencias

Desarrollo

Objetivos Make Disponibles

make help            # Show all available targets
make build           # Build the binary
make test            # Run tests
make test-coverage   # Run tests with coverage
make lint            # Run linter  
make fmt             # Format code
make clean           # Clean build artifacts
make ci              # Run full CI pipeline

Requisitos Previos

Go 1.21 o posterior
Opcional: golangci-lint para linting
Opcional: gosec para escaneo de seguridad

Flujo de Trabajo de Desarrollo

Realizar cambios en el código
Ejecutar pruebas: make test
Formatear código: make fmt
Ejecutar linter: make lint
Compilar binario: make build
Probar manualmente: ./loanpro-mcp-server --help

Respuestas de Ejemplo

Detalles del Préstamo

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

Resultados de Búsqueda

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

Información del Cliente

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

Historial de Transacciones

Transaction History for Loan 619:
- Date: 2025-11-25, Type: payment, Amount: $75022.40, ID: 2356, Status: Active
  Title: Payment Received
  Applied: Principal: $74500.00 Interest: $522.40
- Date: 2025-11-25, Type: payment, Amount: $500.00, ID: 2357, Status: Active
  Title: Additional Payment
  Applied: Principal: $500.00
- Date: 2025-11-20, Type: charge.latefee, Amount: $50.00, ID: 1234, Status: Active
  Title: Late Fee
- Date: 2025-11-18, Type: credit, Amount: $25.00, ID: 1233, Status: Active
  Title: Fee Waiver

Configuración de Registro

El servidor admite registro configurable mediante variables de entorno:

Niveles de Registro

Establezca la variable de entorno LOG_LEVEL para controlar la verbosidad del registro:

DEBUG: Información de depuración detallada incluyendo datos de solicitud/respuesta
INFO: Mensajes operativos generales (predeterminado)
WARN/WARNING: Mensajes de advertencia
ERROR: Solo mensajes de error

Formatos de Registro

Establezca la variable de entorno LOG_FORMAT para controlar el formato de salida:

TEXT: Formato de texto legible por humanos (predeterminado)
JSON: Formato JSON estructurado para agregación de registros

Ejemplos

# Debug level with text format
LOG_LEVEL=DEBUG ./loanpro-mcp-server --transport=stdio

# Info level with JSON format  
LOG_LEVEL=INFO LOG_FORMAT=JSON ./loanpro-mcp-server --transport=http

# Error level only
LOG_LEVEL=ERROR ./loanpro-mcp-server --transport=sse

Salida de Muestra

Formato de Texto (Predeterminado):

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

Formato 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}

Detalles Técnicos

Cumplimiento JSON-RPC 2.0: Implementación completa del protocolo MCP
Registro Estructurado: Niveles y formatos de registro configurables usando slog de Go
Manejo de Errores: Registro integral de errores en stderr con contexto
Análisis de Fechas: Soporta formato de marca de tiempo Unix de LoanPro (/Date(1427829732)/)
Mapeo de Datos Flexible: Maneja diferentes formatos de respuesta de API
Soporte CORS: Solicitudes de origen cruzado habilitadas para integración web
Diseño Modular: Separación limpia entre capas de transporte, herramientas y API

Licencia

Licencia MIT - consulte el archivo LICENSE para más detalles.