Instruction file imported from Gustavo-Kuze/mcp-server-currency-converter (.cursor/rules/service-layer-patterns.mdc). Copyright stays with the author.

Service Layer Patterns

Brasil API Integration

• Base URL: https://brasilapi.com.br/api
• Use fetch with proper headers: { Accept: "application/json" }
• Handle HTTP errors and network failures gracefully

Exchange Rate Priority Logic

• Prefer PTAX closing rates when available: tipo_boletim === "FECHAMENTO PTAX"
• Fall back to last available rate if PTAX not found
• Use appropriate rate for conversion direction:
  • cotacao_venda (sell rate) for foreign currency → BRL
  • cotacao_compra (buy rate) for BRL → foreign currency

Response Structure

• Always return consistent result objects with success boolean
• Include detailed explanations in response messages
• Provide rate details for transparency

Error Handling

• Return null from API request function on failure
• Check for empty cotacoes array
• Provide meaningful error messages for users

Type Safety

• Define interfaces for Brasil API response structures
• Use generic types for service functions
• Export all interfaces used by other modules

Message Formatting

• Include conversion calculations in explanations
• Show both buy and sell rates for transparency
• Format monetary values appropriately (BRL to 2 decimals, foreign to 4)
• Include rate type and timestamp information