MCP Gastos

# 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: ```bash git clone https://github.com/BrayanTM/mcp-basico.git cd mcp-basico ``` 2. Instala las dependencias: ```bash pip install fastmcp ``` ## 🎯 Uso ### Ejecutar el Servidor MCP ```bash python main.py ``` ### Estructura del CSV El archivo `gastos.csv` utiliza la siguiente estructura: ```csv Fecha,Categoría,Cantidad,Método de pago 2025-11-16,Alimentación,45.50,Tarjeta de crédito ``` **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: ```python agregar_gasto( fecha="2025-11-16", categoria="Alimentación", cantidad=45.50, metodo_pago=MetodoPago.TARJETA_CREDITO ) ``` **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 ``` mcp-basico/ ├── main.py # Servidor MCP con tools, resources y prompts ├── gastos.csv # Archivo de datos (generado automáticamente) ├── pyproject.toml # Configuración del proyecto └── README.md # Documentación ``` ## 🔐 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: ```markdown # Registro de Gastos Total de gastos registrados: 34 Total gastado: $1,724.54 ## Gastos por Categoría ### Alimentación - Cantidad de gastos: 11 - Total: $525.20 ### Transporte - Cantidad de gastos: 6 - Total: $93.50 ... ``` ## 🛠️ 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](https://github.com/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.