# 📋 MCP Task Manager Server

Servidor MCP de gestión de tareas con SQLite — Ejercicio 1 del Onboarding de Everglow.

## Qué hace

Expone 4 herramientas (tools) a cualquier cliente MCP (Claude Desktop, Claude Code) para gestionar tareas almacenadas en una base de datos SQLite local. Los datos son dinámicos y persisten entre sesiones.

## Requisitos

- Python 3.11+
- pip

## Instalación

```bash
# Clonar el repositorio
git clone <url-del-repo>
cd mcp-task-server

# Crear entorno virtual (recomendado)
python -m venv .venv
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows

# Instalar dependencias
pip install -r requirements.txt
```

## Conexión con Claude Desktop

Editar el archivo de configuración de Claude Desktop:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

Añadir el servidor en la sección `mcpServers`:

```json
{
  "mcpServers": {
    "task-manager": {
      "command": "/ruta/completa/a/.venv/bin/python",
      "args": ["/ruta/completa/a/mcp-task-server/server.py"]
    }
  }
}
```

> ⚠️ Usa rutas absolutas. Sustituye `/ruta/completa/a/` por la ruta real de tu proyecto.

Reiniciar Claude Desktop. Las tools deberían aparecer en el icono de herramientas (🔨).

## Conexión con Claude Code

Desde la raíz del proyecto:

```bash
claude mcp add task-manager -- python /ruta/completa/a/mcp-task-server/server.py
```

## Tools disponibles

### `list_tasks` (lectura)

Lista tareas con filtros opcionales.

| Parámetro  | Tipo            | Obligatorio | Descripción                                        |
|------------|-----------------|-------------|----------------------------------------------------|
| `status`   | string \| null  | No          | `pendiente`, `en_progreso` o `completada`          |
| `priority` | string \| null  | No          | `baja`, `media`, `alta` o `urgente`                |

**Ejemplo de uso en Claude:**
> "Muéstrame todas las tareas urgentes que estén pendientes"

**Respuesta (JSON):**
```json
{
  "total": 1,
  "tasks": [
    {
      "id": 3,
      "title": "Revisar despliegue en producción",
      "description": "Verificar que el deploy de v2.1 no tiene errores",
      "status": "pendiente",
      "priority": "urgente",
      "created_at": "2025-07-10T09:30:00",
      "updated_at": "2025-07-10T09:30:00"
    }
  ]
}
```

---

### `add_task` (escritura)

Crea una nueva tarea.

| Parámetro     | Tipo   | Obligatorio | Descripción                             |
|---------------|--------|-------------|-----------------------------------------|
| `title`       | string | **Sí**      | Título de la tarea                      |
| `description` | string | No          | Descripción detallada                   |
| `priority`    | string | No          | `baja`, `media` (default), `alta`, `urgente` |

**Ejemplo de uso en Claude:**
> "Crea una tarea urgente: Preparar demo para el cliente Acme, con descripción 'Incluir flujo de email y reporte'"

---

### `update_task` (escritura)

Actualiza estado y/o prioridad de una tarea existente.

| Parámetro  | Tipo            | Obligatorio | Descripción                               |
|------------|-----------------|-------------|-------------------------------------------|
| `task_id`  | integer         | **Sí**      | ID de la tarea                            |
| `status`   | string \| null  | No*         | Nuevo estado                              |
| `priority` | string \| null  | No*         | Nueva prioridad                           |

*Al menos uno de los dos debe indicarse.

**Ejemplo de uso en Claude:**
> "Marca la tarea 3 como completada"

---

### `delete_task` (escritura)

Elimina una tarea por ID.

| Parámetro | Tipo    | Obligatorio | Descripción        |
|-----------|---------|-------------|--------------------|
| `task_id` | integer | **Sí**      | ID de la tarea     |

**Ejemplo de uso en Claude:**
> "Elimina la tarea 5"

---

## Manejo de errores

Todos los errores devuelven JSON con una clave `"error"` y un mensaje descriptivo:

- **Parámetro inválido**: indica los valores permitidos.
- **Tarea no encontrada**: informa el ID buscado.
- **Título vacío**: rechaza la creación.
- **Sin campos para actualizar**: solicita al menos uno.

El servidor **no se cae** ante errores — los captura y devuelve respuestas estructuradas.

## Estructura del proyecto

```
mcp-task-server/
├── server.py           # Servidor MCP (punto de entrada)
├── requirements.txt    # Dependencias Python
├── tasks.db            # Base de datos SQLite (se crea automáticamente)
└── README.md           # Esta documentación
```

## Decisiones técnicas

- **SQLite** como almacenamiento: sin infraestructura externa, datos dinámicos y persistentes, ideal para una demo funcional.
- **FastMCP** (SDK oficial de Anthropic): la forma más directa de crear un servidor MCP en Python, con tipado de parámetros automático.
- **4 tools** en lugar de las 2 mínimas: cubrir el CRUD completo hace el servidor más útil y demuestra mejor el manejo de errores.
- **JSON como formato de respuesta**: estructurado, parseable por Claude, fácil de extender.

## Autor

Implementador Jr. — Onboarding Everglow Innovations SL