# 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.