Expense Tracker

Gestión automatizada de gastos con un backend de Supabase y soporte de categorías jerárquicas.

GitHubPrueba este MCPPatrocinado

Documentación

Expense Tracker Backend

Sistema de seguimiento de gastos impulsado por IA con interfaz de lenguaje natural, categorización inteligente y sincronización en tiempo real.

Arquitectura

El sistema utiliza una arquitectura de dos servidores:

  1. MCP Server: Herramientas principales de seguimiento de gastos expuestas a través de Model Context Protocol
  2. Gemini AI Server: Servidor FastAPI que proporciona interfaz de chat con autenticación

Características

  • 🤖 Gestión de gastos en lenguaje natural mediante Gemini AI
  • 🧠 Categorización inteligente mediante embeddings y búsqueda de similitud
  • 🔐 Autenticación JWT con Supabase
  • 📊 Categorías jerárquicas para organización
  • 🏷️ Sistema de etiquetas predefinidas
  • 📈 Sincronización de datos en tiempo real
  • 🔄 Sistema de aprendizaje que mejora con el tiempo

Inicio Rápido

Requisitos Previos

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Configuración del Entorno

cp .env.example .env
# Add your credentials:
# - SUPABASE_URL
# - SUPABASE_KEY
# - GOOGLE_API_KEY (for Gemini)

Configuración de la Base de Datos

Ejecute los scripts SQL en su Editor SQL de Supabase:

# Core tables
scripts/create_tables.sql
# Embeddings support
scripts/create_embeddings_schema.sql

Ejecutar Ambos Servidores

Terminal 1 - MCP Server:

python run_mcp.py

Terminal 2 - Gemini AI Server:

uvicorn app.servers.gemini.main:app --reload --port 8000

Inicializar Datos

# Populate categories
python scripts/populate_hierarchical_categories.py

# Populate predefined tags
python scripts/populate_predefined_tags.py

Endpoints de API

Interfaz de Chat

  • POST /chat - Enviar comandos en lenguaje natural
  • POST /auth/refresh - Renovar token JWT

Herramientas MCP (a través del chat)

  • Crear gastos a partir de lenguaje natural
  • Auto-categorizar transacciones
  • Obtener resúmenes de gastos
  • Analizar suscripciones
  • Ver transacciones recientes

Flutter Client

consulte https://github.com/keyurgit45/expense-tracker-client

Pruebas

# Run all tests with mocks
ENVIRONMENT=test pytest tests/ -v

# Run specific components
ENVIRONMENT=test pytest tests/test_mcp_tools.py -v
ENVIRONMENT=test pytest tests/test_categorization.py -v

Estructura del Proyecto

backend/
├── app/
│   ├── core/              # Business logic
│   ├── servers/
│   │   ├── gemini/       # AI chat server
│   │   └── mcp/          # MCP tool server
│   └── shared/           # Shared configs
├── scripts/              # Utilities
└── tests/               # Test suite

Categorización con IA

El sistema utiliza un enfoque híbrido:

  1. Genera embeddings para transacciones usando Sentence Transformers
  2. Encuentra transacciones pasadas similares usando pgvector
  3. Utiliza votación ponderada para predecir categorías
  4. Recurre a coincidencia basada en reglas
  5. Aprende de las confirmaciones del usuario

Desarrollo

  • Documentación de API: http://localhost:8000/docs
  • Integración frontend: Configure CORS en el servidor Gemini
  • Las herramientas MCP se pueden probar directamente a través de la interfaz de chat