# MCP Todo Server

Servidor MCP desarrollado en Python para la gestión básica de tareas almacenadas localmente en un archivo JSON.

El proyecto implementa las principales capacidades de Model Context Protocol (MCP): **Resources, Tools y Prompts**, permitiendo consultar tareas pendientes, registrar nuevas tareas, marcar tareas como completadas y generar una plantilla de resumen diario.

## Funcionalidades

El servidor expone las siguientes capacidades:

### Resource — `tasks://pending`

Retorna las tareas que se encuentran pendientes en `tasks.json`.

Las tareas completadas permanecen almacenadas, pero no son incluidas en el resultado del Resource.

### Tool — `add_task`

Permite registrar una nueva tarea proporcionando:

- nombre;
- descripción;
- prioridad (`alta`, `media` o `baja`).

Cada tarea recibe automáticamente un identificador con el formato:

```text
T-001
T-002
T-003
```

La herramienta también valida que la tarea tenga un nombre y que la prioridad corresponda con uno de los valores permitidos.

### Tool — `complete_task`

Permite marcar una tarea como completada utilizando su identificador.

Por ejemplo:

```text
T-001
```

Al encontrar la tarea, su estado `completada` cambia de `false` a `true` y el cambio se guarda en `tasks.json`.

### Prompt — `daily_summary`

Genera una plantilla basada en el estado actual de las tareas.

Considera:

- total de tareas;
- tareas completadas;
- tareas pendientes;
- tareas pendientes de prioridad alta.

La plantilla permite generar un resumen del progreso general y orientar la atención hacia las actividades de mayor prioridad.

## Estructura del proyecto

```text
mcp-todo-server/
│
├── .vscode/
│   └── mcp.json
├── server.py
├── tasks.json
├── requirements.txt
├── README.md
└── .gitignore
```

| Archivo | Descripción |
|---|---|
| `.vscode/mcp.json` | Configuración del servidor MCP para su integración con Visual Studio Code |
| `server.py` | Contiene la implementación del servidor MCP |
| `tasks.json` | Almacena localmente las tareas |
| `requirements.txt` | Contiene las dependencias del proyecto |
| `README.md` | Documentación del proyecto |
| `.gitignore` | Define los archivos y directorios excluidos de Git |

El directorio `.venv` corresponde al entorno virtual local y no se incluye en el repositorio.

## Modelo de datos

Las tareas se almacenan en formato JSON con la siguiente estructura:

```json
{
    "id": "T-001",
    "nombre": "Revisar documento del extraclase",
    "descripcion": "Comprobar que las capturas y explicaciones estén completas",
    "prioridad": "alta",
    "completada": true
}
```

El campo `id` identifica cada tarea, mientras que `completada` permite determinar si debe aparecer en el Resource de tareas pendientes.

## Requisitos

Para ejecutar el proyecto se requiere:

- Python 3
- pip
- Model Context Protocol SDK para Python

Para realizar pruebas con MCP Inspector se utilizó pnpm.

## Instalación

### 1. Clonar el repositorio

```bash
git clone https://github.com/lnnth0440/mcp-todo-server.git
cd mcp-todo-server
```

### 2. Crear el entorno virtual

En Windows:

```powershell
python -m venv .venv
```

### 3. Activar el entorno virtual

En PowerShell:

```powershell
.\.venv\Scripts\Activate.ps1
```

### 4. Instalar las dependencias

```powershell
python -m pip install -r requirements.txt
```

## Ejecución

Con el entorno virtual activo, ejecutar:

```powershell
python server.py
```

El servidor utiliza comunicación mediante entrada y salida estándar (`stdio`) y permanece en ejecución esperando la conexión de un cliente MCP.

Para detenerlo:

```text
Ctrl + C
```

## Pruebas con MCP Inspector

El funcionamiento del servidor puede comprobarse mediante MCP Inspector.

Utilizando pnpm:

```powershell
pnpm dlx @modelcontextprotocol/inspector python server.py
```

Una vez establecida la conexión, MCP Inspector permite descubrir e interactuar con las capacidades expuestas por el servidor:

```text
Resources
└── tasks://pending

Tools
├── add_task
└── complete_task

Prompts
└── daily_summary
```

Estas pruebas permiten verificar la consulta de tareas, la modificación de `tasks.json` mediante las Tools y la generación de la plantilla de resumen diario.

## Integración con Visual Studio Code

El servidor también fue integrado con Visual Studio Code como cliente MCP compatible.

La configuración se encuentra en:

```text
.vscode/mcp.json
```

El archivo contiene la definición del servidor local:

```json
{
  "servers": {
    "mcp-todo-server": {
      "type": "stdio",
      "command": "C:\\Users\\jmuri\\Documents\\mcp-todo-server\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\jmuri\\Documents\\mcp-todo-server\\server.py"
      ]
    }
  }
}
```

Para iniciar el servidor desde Visual Studio Code:

1. Abrir el proyecto en Visual Studio Code.
2. Abrir la paleta de comandos con `Ctrl + Shift + P`.
3. Ejecutar `MCP: List Servers`.
4. Seleccionar `mcp-todo-server`.
5. Elegir la opción `Start`.

Cuando la conexión se establece correctamente, Visual Studio Code muestra el servidor en estado `Running` y descubre las herramientas:

```text
add_task
complete_task
```

Desde el chat de Visual Studio Code es posible utilizar lenguaje natural para invocar las herramientas del servidor.

Por ejemplo:

```text
Agrega una nueva tarea llamada "Preparar entrega final",
con la descripción "Revisar README, capturas y documento final"
y prioridad media.
```

Visual Studio Code utiliza la herramienta `add_task` del servidor MCP y actualiza el archivo `tasks.json`.

También puede utilizarse `complete_task` para marcar tareas como completadas y `daily_summary` para generar un resumen del estado actual de las tareas.

## Tecnologías utilizadas

- Python
- Model Context Protocol (MCP)
- JSON
- MCP Inspector
- Visual Studio Code
- Git
- GitHub

## Autora

**Jendry Linneth Murillo Pérez**  
Programación IV  
II Cuatrimestre, 2026