MCP Gastos

Servidor MCP (Model Context Protocol) para la gestión de gastos personales mediante un archivo CSV. Construido con FastMCP, este proyecto permite a agentes de IA agregar, consultar y analizar gastos de manera estructurada.

🚀 Características

• Tool: agregar_gasto - Añade nuevos gastos al registro CSV

• Resource: resource://gastos - Consulta gastos formateados para consumo de LLMs

• Prompt: Plantilla para generar resúmenes de gastos de los últimos 5 días

• Validación: Enum de métodos de pago para garantizar consistencia

• Estadísticas: Cálculo automático de totales por categoría y método de pago

📋 Requisitos

• Python >= 3.14

• FastMCP >= 2.13.1

🔧 Instalación

1. Clona el repositorio:

2. Instala las dependencias:

🎯 Uso

Ejecutar el Servidor MCP

Estructura del CSV

El archivo gastos.csv utiliza la siguiente estructura:

Columnas:

• Fecha: Formato ISO 8601 (YYYY-MM-DD)

• Categoría: Texto libre (ej: "Alimentación", "Transporte", "Salud")

• Cantidad: Número decimal con 2 decimales

• Método de pago: Enum validado (Tarjeta de débito, Tarjeta de crédito, Efectivo)

Funcionalidades del MCP

Tool: agregar_gasto

Añade un nuevo gasto al archivo CSV:

Parámetros:

• fecha (str): Fecha en formato YYYY-MM-DD

• categoria (str): Categoría del gasto

• cantidad (float): Monto del gasto

• metodo_pago (MetodoPago): Enum con valores válidos

Resource: resource://gastos

Retorna todos los gastos en formato Markdown estructurado, incluyendo:

• Total de gastos registrados

• Suma total gastada

• Agrupación por categoría con subtotales

• Listado detallado de todos los gastos

Prompt: prompt_agregar_gasto

Genera un resumen inteligente de los gastos de los últimos 5 días, agrupados por día y categoría.

📂 Estructura del Proyecto

🔐 Métodos de Pago Válidos

El servidor valida los métodos de pago mediante un Enum:

• MetodoPago.TARJETA_DEBITO → "Tarjeta de débito"

• MetodoPago.TARJETA_CREDITO → "Tarjeta de crédito"

• MetodoPago.EFECTIVO → "Efectivo"

📊 Ejemplo de Salida

Al consultar el resource resource://gastos, obtendrás un formato como:

🛠️ Convenciones de Desarrollo

• Encoding: Siempre usar utf-8 para compatibilidad con caracteres especiales

• CSV: Usar newline='' al abrir archivos en modo escritura

• Formato de cantidades: Siempre .2f para dos decimales

• Manejo de errores: Try/except con mensajes descriptivos en español

• Output para LLMs: Markdown estructurado con jerarquía clara

👤 Autor

BrayanTM

• GitHub: @BrayanTM

Nota: Este servidor MCP está diseñado para ser consumido por agentes de IA que implementen el protocolo MCP, permitiendo gestión automatizada de gastos mediante lenguaje natural.