Bancoach MCP Server

Web app Repo: https://github.com/marielgonzalezg/CyphoWeb

MCP Client Repo: https://github.com/hectorpablogzz/MCPClient

Servidor MCP diseñado para conectar Bancoach con Supabase y los servicios públicos de Banxico. Expone herramientas que permiten consultar balances, transacciones, metas y productos financieros de los usuarios, así como indicadores macroeconómicos (tipo de cambio, CETES, inflación) que el asistente puede usar en sus flujos conversacionales.

Arquitectura

Requisitos previos

• Python 3.10 o superior.
• Acceso a una instancia de Supabase con las tablas y funciones RPC esperadas (usuarios, transacciones, creditos, metas, resumen_balance, resumen_afore).
• Token vigente de la API de Banxico.

Configuración

1. Clona este repositorio y entra al directorio del proyecto.

2. Crea un entorno virtual (opcional, pero recomendado):

   python -m venv .venv
   source .venv/bin/activate

3. Instala las dependencias:

   pip install -r requirements.txt

4. Configura las variables de entorno en un archivo .env:

   • NEXT_PUBLIC_SUPABASE_URL: URL del proyecto Supabase.
   • NEXT_PUBLIC_SUPABASE_ANON_KEY: llave pública (anon) de Supabase.
   • BANXICO_TOKEN: reemplaza el valor hardcodeado en main.py agregando esta variable al entorno para fortalecer la seguridad.

   Ejemplo:

   NEXT_PUBLIC_SUPABASE_URL=https://TU_INSTANCIA.supabase.co
   NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJI...
   BANXICO_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ejecución

1. Asegúrate de que el archivo .env esté configurado.

2. Ejecuta el servidor MCP:

   python main.py

   El servidor quedará disponible por defecto en http://0.0.0.0:8000.

Herramientas disponibles

Las herramientas registradas en main.py cubren los siguientes casos de uso:

• saludar(id_usuario): devuelve un saludo personalizado usando los datos del usuario en Supabase.
• consultar_transacciones(...): lista transacciones con filtros opcionales por rango de fechas (máx. 31 días), categoría y tipo (gasto o ingreso).
• consultar_balance(id_usuario): resume ingresos, gastos y balance usando la función RPC resumen_balance.
• consultar_afore(id_usuario): obtiene el total acumulado en AFORE desde resumen_afore.
• consultar_creditos(id_usuario): muestra créditos del usuario con datos de monto, tasa, fechas y estado.
• consultar_metas(id_usuario): lista metas financieras activas del usuario.
• agregar_meta(...): inserta una nueva meta validando formato de fecha y categoría.
• cambio_dolar(dolares, pesos): consulta el tipo de cambio spot USD/MXN y calcula conversiones.
• cetes(dinero, dias): estima rendimiento de CETES para 28, 91, 182 o 364 días usando las series oficiales.
• calcular_inflacion(fecha_inicio, fecha_final): calcula variación porcentual de inflación entre dos fechas.

Desarrollo y buenas prácticas

• Revisa los esquemas de Supabase antes de desplegar cambios para garantizar compatibilidad con las herramientas.
• Considera agregar pruebas o mocks para las llamadas a Supabase y Banxico si automatizas la validación del proyecto.