mcp-basico

BrayanTM/mcp-basico

3.2

If you are the rightful owner of mcp-basico and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Servidor MCP para la gestión de gastos personales mediante un archivo CSV.

Tools
1
Resources
0
Prompts
0

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:
git clone https://github.com/BrayanTM/mcp-basico.git
cd mcp-basico
  1. Instala las dependencias:
pip install fastmcp

🎯 Uso

Ejecutar el Servidor MCP

python main.py

Estructura del CSV

El archivo gastos.csv utiliza la siguiente estructura:

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:

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:

# 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

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.