📋 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

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

{
  "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:

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):

{
  "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