bcv-exchange-rate

v2.0.1

Published

9 days ago

Librería profesional de Node.js y servidor MCP para el rastreo de indicadores económicos oficiales de Venezuela (BCV), Colombia (TRM - COP) y Brasil (PTAX - BRL). Especializada en monedas fronterizas.

Downloads

735

bcv-exchange-rate

Librería profesional de Node.js y servidor MCP para consultar indicadores económicos oficiales de Venezuela (BCV), Colombia (TRM) y Brasil (PTAX). Extrae los datos directamente del Banco Central de Venezuela, del portal de datos abiertos del Gobierno de Colombia y del Banco Central do Brasil, con tipado estricto, reintentos con backoff, caché en memoria activa por defecto, jerarquía de errores tipada y logger basado en interfaz, sin dependencias forzadas.

Características

Multi-indicador. Tasas oficiales del BCV (USD, EUR, CNY, TRY, RUB), TRM de Colombia (COP) y dólar PTAX de Brasil (BRL).
Servidor MCP integrado. npx bcv-exchange-rate expone las tres fuentes en cuatro tools del Model Context Protocol para Claude, Cursor y cualquier cliente MCP.
CLI incluida. Consulta cualquier fuente desde la terminal (npx bcv-exchange-rate o el alias global xrate) con salida JSON apta para scripts.
Historial bancario paginado. Tasas de compra y venta por institución financiera venezolana.
Reintentos automáticos con backoff exponencial configurable.
Caché en memoria con TTL por llamada y stale-while-error opcional.
Jerarquía de errores tipada (NetworkError, TrmApiError, BrlApiError, ValidationError).
Logger basado en interfaz. Compatible con winston, pino, bunyan o console, sin dependencias forzadas.
TLS seguro por defecto (strictSSL: true), con desactivación explícita cuando sea necesario. Los fallos de certificado lanzan TlsError sin reintentos, con la recomendación del flag en el mensaje, y toda respuesta ecoa strictSSL para saber si la data se obtuvo sin validación.
Dual CJS/ESM con declaraciones .d.ts.
Estado por sección (status.current, status.history) para detectar fallos parciales.
Cobertura del 100 % forzada en CI.

Instalación

npm install bcv-exchange-rate

Requiere Node.js 20 LTS o superior. Si usas winston como logger (opcional):

npm install winston

Inicio rápido

import { getBcvRates, getTrmRates, getBrlRates } from 'bcv-exchange-rate';

const bcv = await getBcvRates({ currencies: 'USD', includeHistory: false });
console.log(`USD/VES: ${bcv.current.USD} (vigencia ${bcv.effectiveDate})`);

const trm = await getTrmRates({ limit: 1 });
console.log(`TRM: ${trm?.current.value} COP`);

const brl = await getBrlRates({ days: 7 });
console.log(`PTAX venta: ${brl?.current.sell} BRL por USD (${brl?.current.dateTime})`);

Versión CommonJS:

const { getBcvRates } = require('bcv-exchange-rate');

Ejemplo con caché y reintentos

const bcv = await getBcvRates({
  currencies: ['USD', 'EUR'],
  retries: 3,
  retryDelayMs: 500,
  cacheTtlMs: 60_000,
  cacheStaleTtlMs: 10 * 60_000,
});

if (bcv.status.current === 'failed') {
  console.warn('Tasa actual no disponible; se usa el historial como alternativa');
}

CLI

Consulta cualquier fuente directamente desde la terminal con npx (o con xrate si lo instalas global):

npx bcv-exchange-rate                  # tasas BCV (comando por defecto) + histórico
npx bcv-exchange-rate bcv --currencies USD,EUR --days 3 --no-history
npx bcv-exchange-rate history --days 3 # solo histórico bancario BCV
npx bcv-exchange-rate trm --limit 5    # TRM de Colombia
npx bcv-exchange-rate brl --days 30 --limit 5 --offset 5   # dólar PTAX de Brasil, paginado
npx bcv-exchange-rate --help           # todos los comandos y flags

La salida es JSON formateado por stdout (exit 0); los errores van por stderr (exit 1), apto para pipes y scripts.

Instalación global con alias corto:

npm install -g bcv-exchange-rate
xrate                # equivale a "xrate bcv"
xrate trm --limit 1

Flags globales de todos los comandos: --timeout MS (default 25000), --retries N (default 2). Los comandos del BCV aceptan --strict-ssl para activar la validación TLS (desactivada por defecto en la CLI: el portal del BCV sirve una cadena de certificados incompleta).

Servidor MCP

El mismo binario es un servidor Model Context Protocol por stdio: cuando lo lanza un cliente MCP (stdin por pipe, sin argumentos) sirve el protocolo automáticamente; cuando lo ejecuta una persona en una terminal interactiva actúa como CLI.

Configuración en clientes MCP

Claude Code:

claude mcp add bcv-exchange-rate -- npx bcv-exchange-rate

Claude Desktop / Cursor / cualquier cliente con mcpServers (claude_desktop_config.json, .mcp.json, etc.):

{
  "mcpServers": {
    "bcv-exchange-rate": {
      "command": "npx",
      "args": ["bcv-exchange-rate"]
    }
  }
}

Tools disponibles

`get_bcv_rates` — Tasas oficiales BCV (Venezuela)

Tasas de cambio oficiales del Banco Central de Venezuela (VES por unidad de divisa) y, opcionalmente, el histórico informativo del sistema bancario.

| Atributo | Tipo | Default | Descripción | | ---------------- | ----------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | currencies | ("USD" \| "EUR" \| "CNY" \| "TRY" \| "RUB")[] | todas | Códigos de moneda a incluir. | | includeCurrent | boolean | true | Incluir las tasas actuales de la portada del BCV. | | includeHistory | boolean | true | Incluir el histórico bancario. | | days | integer ≥ 1 | 7 | Ventana de días del histórico. | | page | integer ≥ 0 | 0 | Página del histórico. | | strictSSL | boolean | false | Validación TLS. El portal del BCV sirve una cadena de certificados incompleta, por lo que el servidor MCP la desactiva por defecto (la librería mantiene true). | | timeout | integer ≥ 1 | 25000 | Timeout de la petición en ms. | | retries | integer ≥ 0 | 2 | Reintentos ante fallos transitorios. | | cacheTtlMs | integer ≥ 0 | 60000 | TTL de caché fresca en ms; 0 desactiva la caché. |

`get_bcv_history` — Histórico bancario BCV (Venezuela)

Solo las tasas informativas históricas del sistema bancario venezolano (compra/venta por banco y fecha).

| Atributo | Tipo | Default | Descripción | | ------------ | ------------- | ------- | -------------------------------------------------- | | days | integer ≥ 1 | 7 | Ventana de días hacia atrás. | | page | integer ≥ 0 | 0 | Página del listado. | | strictSSL | boolean | false | Validación TLS (ver nota en get_bcv_rates). | | timeout | integer ≥ 1 | 25000 | Timeout de la petición en ms. | | retries | integer ≥ 0 | 2 | Reintentos ante fallos transitorios. | | cacheTtlMs | integer ≥ 0 | 60000 | TTL de caché fresca en ms; 0 desactiva la caché. |

`get_trm_rates` — TRM oficial (Colombia)

Tasa Representativa del Mercado (COP por USD) desde el portal de datos abiertos del Gobierno de Colombia (datos.gov.co).

| Atributo | Tipo | Default | Descripción | | ------------ | ---------------- | ---------- | -------------------------------------------------- | | limit | integer 1-1000 | 10 | Máximo de registros a devolver. | | offset | integer ≥ 0 | 0 | Desplazamiento de paginación. | | days | integer ≥ 1 | sin filtro | Ventana de días hacia atrás (vigenciahasta >=). | | timeout | integer ≥ 1 | 25000 | Timeout de la petición en ms. | | retries | integer ≥ 0 | 2 | Reintentos ante fallos transitorios. | | cacheTtlMs | integer ≥ 0 | 60000 | TTL de caché fresca en ms; 0 desactiva la caché. |

`get_brl_rates` — Dólar PTAX oficial (Brasil)

Cotización oficial USD/BRL (dólar PTAX, compra y venta) desde la API de datos abiertos del Banco Central do Brasil. Devuelve null cuando la ventana no contiene cotizaciones (fines de semana o feriados).

| Atributo | Tipo | Default | Descripción | | ------------ | ---------------- | --------------- | -------------------------------------------------- | | days | integer ≥ 1 | 7 | Ventana de días hacia atrás. | | limit | integer 1-1000 | toda la ventana | Máximo de registros a devolver (OData $top). | | offset | integer ≥ 0 | 0 | Registros a saltar para paginar (OData $skip). | | timeout | integer ≥ 1 | 25000 | Timeout de la petición en ms. | | retries | integer ≥ 0 | 2 | Reintentos ante fallos transitorios. | | cacheTtlMs | integer ≥ 0 | 60000 | TTL de caché fresca en ms; 0 desactiva la caché. |

Todas las tools devuelven el payload por partida doble: como JSON en el contenido de texto y como structuredContent.data validado contra el outputSchema que cada tool declara en tools/list — el servidor es autodescriptivo y cualquier cliente o agente puede integrarse desde esa respuesta sin documentación externa. Los errores de la librería (red, TLS, validación, parseo) se reportan como respuestas MCP con isError: true sin tumbar el servidor.

Especificación completa a nivel de protocolo (handshake, esquemas de salida, intercambios reales y recetas para agentes): docs/mcp.md.

Estructura de respuesta unificada

Las tres fuentes comparten el mismo esqueleto de salida. Los campos que no aplican al paradigma de una fuente son null (nunca se omiten), de modo que el shape es idéntico:

{
  current:    ...,        // varía por fuente: multi-moneda (BCV), valor (TRM), compra/venta (BRL)
  history:    [...],      // ítems propios de cada fuente
  pagination: {
    limit:   number | null,   // null: no solicitado, o la fuente pagina por página (BCV)
    offset:  number | null,   // null: la fuente pagina por página (BCV)
    page:    number | null,   // null: la fuente pagina por limit/offset (TRM, BRL)
    count:   number,          // registros devueltos
    hasMore: boolean | null   // null: la fuente no puede saberlo (TRM, BRL)
  },
  range: { startDate, endDate } | null,  // ventana de días aplicada (ISO 8601)
  strictSSL: boolean                     // false = la data se obtuvo SIN validación TLS
}

| Campo | BCV | TRM | BRL | | ----------------------------- | ----------------------- | ------------------------------------- | ------------------------------------- | | pagination.limit / offset | null (usa page) | reales | reales (limit: null si no se pidió) | | pagination.page | real | null | null | | pagination.hasMore | real (pager del portal) | null | null | | range | ventana de days | ventana de days o null sin filtro | ventana de days |

BcvResponse añade además effectiveDate y status (fallos parciales por sección).

Comportamiento ante certificados TLS inválidos

Un certificado expirado, autofirmado o con cadena incompleta lanza TlsError de inmediato (sin gastar reintentos: el fallo es determinista). El mensaje incluye la recomendación: reintentar con strictSSL: false (librería/tools MCP) o sin --strict-ssl (CLI) si aceptas el riesgo.
En getBcvRates con ambas secciones, un fallo TLS en una sección no tumba la otra: se marca status.<sección>: 'failed' y el resto se entrega.
El campo strictSSL de la respuesta indica siempre cómo se obtuvo la data: false significa que la validación TLS estuvo desactivada en esa llamada.

Documentación

La documentación extendida vive en docs/:

Primeros pasos

Referencia

Guías temáticas

Operaciones

Solución de problemas

Desarrollo

npm install
npm test             # Jest con cobertura del 100 % forzada.
npm run lint         # ESLint.
npm run format       # Prettier.
npm run build        # Dual CJS/ESM, declaraciones, CLI y servidor MCP.

Más detalles en CONTRIBUTING.md.