LoanPro MCP Server

Um servidor MCP que fornece acesso somente leitura aos dados financeiros do LoanPro.

Documentação

LoanPro MCP Server

Um servidor Model Context Protocol (MCP) que expõe acesso somente leitura aos dados do LoanPro por meio de múltiplos protocolos de transporte: HTTP, Server-Sent Events (SSE) e stdio.

Recursos

Múltiplos Protocolos de Transporte: suporte a HTTP, SSE e stdio
Integração Somente Leitura com LoanPro: acesso seguro a dados de empréstimos e clientes
Dados Financeiros Abrangentes: saldos, pagamentos, status e histórico de pagamentos
Arquitetura Modular: separação clara de responsabilidades com pacotes dedicados
Compatível com MCP: implementação completa do Model Context Protocol
Construído com Go: alto desempenho e confiabilidade
Suporte a CORS: requisições entre origens para integração web

Arquitetura

O servidor é organizado em pacotes modulares para facilitar a manutenção:

├── 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

Configuração

Clone o repositório
Copie .env.example para .env e configure suas credenciais da API do LoanPro:
```
cp .env.example .env
```

Edite .env com os detalhes da sua API do 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

Execução

Transporte HTTP (Padrão)

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

O servidor fornecerá os seguintes endpoints:

POST /mcp - Requisições MCP
GET / - Informações do servidor
GET /health - Verificação de saúde

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

Comparação de Transportes

Transporte	Caso de Uso	Comunicação	Endpoints
HTTP	Clientes REST, aplicações web, testes	HTTP POST padrão	`/mcp`, `/`, `/health`
SSE	Navegadores web, aplicações em tempo real	Eventos enviados pelo servidor	`/sse`, `/`
Stdio	Clientes MCP (Claude Desktop)	stdin/stdout bidirecional	N/A

Ferramentas Disponíveis

get_loan

Recupera informações abrangentes do empréstimo por ID, incluindo saldos, cronogramas de pagamento e detalhes do cliente.

Parâmetros:

loan_id (obrigatório): O ID do empréstimo a ser recuperado

Retorna: Detalhes completos do empréstimo com saldo principal, valor de quitação, informações do próximo pagamento, dias em atraso, status e informações do cliente.

search_loans

Busca empréstimos com filtros e termos de pesquisa.

Parâmetros:

search_term (opcional): Termo de pesquisa para corresponder ao nome do cliente, ID de exibição ou título
status (opcional): Filtra por status do empréstimo
limit (opcional): Número máximo de resultados (padrão: 10)

Retorna: Lista de empréstimos correspondentes com informações básicas e dados financeiros.

get_customer

Recupera informações do cliente por ID.

Parâmetros:

customer_id (obrigatório): O ID do cliente a ser recuperado

Retorna: Detalhes do cliente, incluindo nome, e-mail, telefone e data de criação.

search_customers

Busca clientes com um termo de pesquisa.

Parâmetros:

search_term (opcional): Termo de pesquisa para corresponder a nomes de clientes, e-mail ou SSN
limit (opcional): Número máximo de resultados (padrão: 10)

Retorna: Lista de clientes correspondentes com informações de contato.

get_loan_payments

Obtém o histórico de pagamentos de um empréstimo.

Parâmetros:

loan_id (obrigatório): O ID do empréstimo para obter o histórico de pagamentos

Retorna: Lista cronológica de pagamentos feitos no empréstimo com datas, valores, IDs de pagamento e status (Ativo/Inativo).

get_loan_transactions

Obtém o histórico detalhado de transações de um empréstimo, incluindo pagamentos, cobranças, créditos e ajustes.

Parâmetros:

loan_id (obrigatório): O ID do empréstimo para obter o histórico de transações

Retorna: Histórico abrangente de transações, incluindo:

Tipo de transação (pagamento, cobrança, crédito, ajuste, etc.)
Valor, data, ID e status da transação
Detalhamento da aplicação do pagamento (principal, juros, taxas, escrow)
Título e descrição da transação
Trilha de auditoria completa de todas as atividades do empréstimo

Exemplos 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}'

Configuração do Cliente MCP (Claude Desktop)

Para binário 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-fonte 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

Inicie o servidor com transporte SSE:

go run . --transport=sse

Conecte-se ao endpoint SSE:

http://localhost:8080/sse

Compilação

Para compilar um binário autônomo:

go build -o loanpro-mcp-server .

Testes

Executando Testes

Usando o Makefile fornecido:

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

Ou diretamente com Go:

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

Cobertura de Testes

Gere e visualize o relatório 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

Integração Contínua

O projeto inclui workflows do GitHub Actions que automaticamente:

Executam testes em múltiplas versões do Go (1.22.x, 1.23.x, 1.24.x)
Compilam e testam o binário

Estrutura de Testes

tools/ - Testes unitários para implementações de ferramentas MCP com cliente LoanPro simulado
transport/ - Testes unitários para transportes HTTP, SSE e stdio com handlers simulados
loanpro/ - Testes unitários para tipos de dados, parsing de datas e métodos de empréstimo
main_test.go - Testes de integração para inicialização do servidor e manipulação do protocolo MCP

Simulação (Mocking)

Os testes usam implementações simuladas (mocks) para evitar dependências externas:

MockLoanProClient - Simula respostas da API do LoanPro
MockMCPHandler - Simula a manipulação do protocolo MCP
O design baseado em interfaces permite testes fáceis e injeção de dependências

Desenvolvimento

Alvos Make Disponíveis

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

Pré-requisitos

Go 1.21 ou posterior
Opcional: golangci-lint para linting
Opcional: gosec para varredura de segurança

Fluxo de Trabalho de Desenvolvimento

Faça alterações no código
Execute os testes: make test
Formate o código: make fmt
Execute o linter: make lint
Compile o binário: make build
Teste manualmente: ./loanpro-mcp-server --help

Exemplos de Respostas

Detalhes do Empréstimo

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

Resultados de Busca

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

Informações do 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

Histórico de Transações

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

Configuração de Logging

O servidor suporta logging configurável por meio de variáveis de ambiente:

Níveis de Log

Defina a variável de ambiente LOG_LEVEL para controlar o nível de detalhes do logging:

DEBUG: Informações detalhadas de depuração, incluindo dados de requisição/resposta
INFO: Mensagens operacionais gerais (padrão)
WARN/WARNING: Mensagens de aviso
ERROR: Apenas mensagens de erro

Formatos de Log

Defina a variável de ambiente LOG_FORMAT para controlar o formato de saída:

TEXT: Formato de texto legível por humanos (padrão)
JSON: Formato JSON estruturado para agregação de logs

Exemplos

# 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

Exemplo de Saída

Formato de Texto (Padrão):

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}

Detalhes Técnicos

Conformidade com JSON-RPC 2.0: Implementação completa do protocolo MCP
Logging Estruturado: Níveis e formatos de log configuráveis usando o slog do Go
Tratamento de Erros: Logging abrangente de erros para stderr com contexto
Parsing de Datas: Suporta o formato de timestamp Unix do LoanPro (/Date(1427829732)/)
Mapeamento Flexível de Dados: Lida com diferentes formatos de resposta da API
Suporte a CORS: Requisições entre origens habilitadas para integração web
Design Modular: Separação clara entre camadas de transporte, ferramentas e API

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.