Agente de Seguimiento de Gastos

Un rastreador de gastos personal impulsado por IA que convierte solicitudes en lenguaje natural en operaciones estructuradas de base de datos. El proyecto combina una interfaz receptiva de Streamlit, el uso de herramientas de Claude, un servidor MCP y almacenamiento local SQLite.

Qué demuestra este proyecto

• Uso de herramientas agéntico y de múltiples pasos para flujos de trabajo reales de base de datos

• Una separación clara entre el modelo de lenguaje, el transporte MCP y la capa de datos

• Un bucle directo de llamada a herramientas de Claude sin un marco de orquestación

• Validación de entrada, comportamiento asistente acotado y manejo seguro de datos locales

• Pruebas de humo automatizadas e integración continua

• Una interfaz de usuario receptiva para ingreso, conversación e información sobre gastos

Related MCP server: Expense Tracker MCP Server

Características del producto

• Agregar gastos mediante un formulario o una solicitud en lenguaje natural

• Almacenar la fecha, el monto, la categoría y la descripción de cada transacción

• Buscar, actualizar, eliminar y resumir gastos a través de herramientas MCP

• Revisar totales, transacciones recientes y gastos por categoría

• Preguntar al asistente financiero enfocado para obtener información basada en la base de datos

• Mantener los datos de gastos locales en un archivo SQLite

Arquitectura

flowchart LR
    U[User] --> UI[Streamlit or CLI]
    UI --> A[Claude agent]
    A -->|Tool request| C[MCP client]
    C -->|stdio| S[MCP server]
    S -->|DB-API 2.0| D[(SQLite)]
    D --> S
    S -->|Structured result| A
    A --> UI

Claude nunca accede directamente a SQLite. Selecciona entre los esquemas de herramientas MCP, y el servidor es dueño de cada lectura y escritura validada de la base de datos.

Ejemplos de flujos de trabajo del agente

Tecnología

Inicio rápido

Requisitos:

• Python 3.11 o más reciente

• Una clave API de Anthropic para el asistente

Crear y activar un entorno virtual:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

Para macOS o Linux, activar el entorno con:

source .venv/bin/activate

Crear un archivo de entorno local y agregar ANTHROPIC_API_KEY:

Copy-Item .env.example .env

Crear el esquema de la base de datos y las categorías iniciales, luego iniciar la aplicación:

python db_setup.py
streamlit run streamlit_app.py

El servidor MCP usa stdio y se inicia automáticamente cuando un cliente se conecta.

Verificaciones de calidad

Instalar las dependencias de desarrollo y ejecutar las mismas verificaciones que en CI:

python -m pip install -r requirements-dev.txt
python -m black --check .
python -m compileall -q agent.py client_test.py db_setup.py mcp_client.py server.py streamlit_app.py
python -m pytest -q
python client_test.py

client_test.py ejercita las 18 herramientas MCP y elimina sus registros temporales cuando la prueba de humo finaliza.

Herramientas MCP

El servidor expone 18 herramientas:

• Gestión de categorías: list_categories, add_category, rename_category, delete_category, get_category_name

• Gestión de gastos: add_expense, update_expense, delete_expense, list_expenses, search_expenses, expenses_by_category, total_expense_by_category, total_expense, monthly_summary

• Consultas de apoyo: current_date, find_category, get_expense, expenses_between

Estructura del proyecto

Configuración

El archivo .env y expenses.db están excluidos de Git. Las claves API y los datos personales de gastos permanecen fuera del repositorio.

Para recrear la base de datos con una tabla de gastos vacía:

python db_setup.py --reset