Servidor Todo MCP

Un servidor de gestión de tareas robusto y persistente construido sobre el Protocolo de Contexto de Modelo (MCP) usando Python y FastMCP.

Descripción general

El Servidor Todo MCP proporciona a los modelos de lenguaje y agentes de IA una interfaz de gestión de tareas persistente y con estado. Construido con el SDK oficial de Python para MCP (FastMCP), expone herramientas que permiten a los asistentes de IA crear, rastrear, filtrar y completar tareas directamente dentro de su flujo de trabajo.

El estado se persiste localmente en un almacenamiento JSON estructurado (tasks.json), lo que garantiza que los datos de las tareas sobrevivan a reinicios del servidor, reconexiones de clientes y sesiones de agente de múltiples turnos. La comunicación sigue la especificación MCP usando JSON-RPC 2.0 a través de la entrada/salida estándar (stdio).

Related MCP server: mcpappwrite

Arquitectura y flujo de datos

+-------------------------------------------------------------------+
|                        MCP Host / AI Client                       |
|               (Claude Desktop, Cursor, Antigravity)               |
+-------------------------------------------------------------------+
                                  |
                   JSON-RPC 2.0 over stdin / stdout
                                  v
+-------------------------------------------------------------------+
|                       Todo MCP Server                             |
|                                                                   |
|   +-----------------------------------------------------------+   |
|   |                       FastMCP Engine                      |   |
|   |  - Protocol negotiation & schema reflection               |   |
|   |  - Tool dispatch & argument validation (Pydantic/Typing)  |   |
|   +-----------------------------------------------------------+   |
|                                 |                                 |
|   +-----------------------------+-----------------------------+   |
|   |                             |                             |   |
|   v                             v                             v   |
| [ add_task ]             [ list_tasks ]             [ complete_task ]
|   |                             |                             |   |
|   +-----------------------------+-----------------------------+   |
|                                 |                                 |
|                                 v                                 |
|   +-----------------------------------------------------------+   |
|   |                    Storage Controller                     |   |
|   |  - Atomic read/write operations                           |   |
|   |  - Schema serialization with ISO 8601 UTC timestamps      |   |
|   +-----------------------------------------------------------+   |
+-------------------------------------------------------------------+
                                  |
                                  v
+-------------------------------------------------------------------+
|                      Local Storage: tasks.json                    |
+-------------------------------------------------------------------+

Referencia de herramientas

El servidor expone tres herramientas distintas para el ciclo de vida completo de la gestión de tareas.

1. add_task

Crea un nuevo elemento de tarea y lo agrega al almacenamiento persistente.

• Descripción: Agregar una nueva tarea a la lista de tareas pendientes.

• Parámetros:

  • title (cadena, obligatorio): Descripción de la tarea. La longitud debe estar entre 1 y 200 caracteres.

  • priority (cadena, opcional): Nivel de urgencia. Valores aceptados: "low", "medium", "high". Valor predeterminado: "medium".

• Reglas de validación:

  • Las cadenas vacías o que solo contienen espacios en blanco se rechazan.

  • Los títulos que superen los 200 caracteres devuelven un error.

  • Los valores de prioridad no conformes fallan en la validación del esquema.

Solicitud de ejemplo:

{
  "title": "Implement integration test suite",
  "priority": "high"
}

Respuesta de ejemplo:

Task added!
  ID:       1
  Title:    Implement integration test suite
  Priority: high
  Status:   pending

2. list_tasks

Recupera las tareas guardadas con filtrado opcional por estado.

• Descripción: Listar tareas de la lista de tareas pendientes con filtrado de estado opcional.

• Parámetros:

  • status (cadena, opcional): Criterio de filtro. Valores aceptados: "all", "pending", "done". Valor predeterminado: "all".

• Formato: Devuelve una tabla ASCII formateada que resume los ID de tareas, los indicadores de estado, los niveles de prioridad y los títulos.

Solicitud de ejemplo:

{
  "status": "pending"
}

Respuesta de ejemplo:

Tasks (pending) — 2 found:

  ID  Status    Priority Title
————  ————————— ———————— ————————————————————————————————————————
   1  pending   high     Implement integration test suite
   2  pending   medium   Update project documentation

3. complete_task

Marca una tarea existente como completada mediante su identificador entero único.

• Descripción: Marcar una tarea como hecha mediante su ID numérico.

• Parámetros:

  • task_id (entero, obligatorio): El identificador numérico único asignado a la tarea.

• Comportamiento:

  • Actualiza el estado de la tarea a "done".

  • Establece el campo completed_at con la marca de tiempo UTC actual en formato ISO 8601.

  • Idempotente: si la tarea ya está completada, la herramienta notifica al cliente sin corromper las marcas de tiempo.

  • Si el ID no existe, se devuelve una respuesta de error con la lista de ID válidos actuales.

Solicitud de ejemplo:

{
  "task_id": 1
}

Respuesta de ejemplo:

Task 1 completed!
  Title:        Implement integration test suite
  Completed at: 2026-08-20T09:46:17.466797+00:00

Tabla resumen de herramientas

Modelo de datos y persistencia

Los registros de tareas se serializan como matrices JSON codificadas en UTF-8. De forma predeterminada, los registros se almacenan en tasks.json en el directorio de trabajo actual. La ruta del archivo de almacenamiento se puede personalizar mediante la variable de entorno TODO_FILE.

Definición del esquema

[
  {
    "id": 1,
    "title": "Implement integration test suite",
    "priority": "high",
    "status": "done",
    "created_at": "2026-08-20T09:46:17.362387+00:00",
    "completed_at": "2026-08-20T09:46:17.466797+00:00"
  },
  {
    "id": 2,
    "title": "Update project documentation",
    "priority": "medium",
    "status": "pending",
    "created_at": "2026-08-20T09:46:17.384689+00:00",
    "completed_at": null
  }
]

Especificaciones de campos

• id (entero): Identificador entero positivo de incremento automático.

• title (cadena): Cadena de descripción de la tarea (1-200 caracteres).

• priority (cadena): Clasificación de urgencia ("low", "medium", "high").

• status (cadena): Etapa del ciclo de vida ("pending" o "done").

• created_at (cadena): Marca de tiempo UTC en formato ISO 8601 registrada en la creación.

• completed_at (cadena o null): Marca de tiempo UTC en formato ISO 8601 registrada al completarse.

Requisitos

• Python: Versión 3.10 o superior

• Dependencias:

  • mcp[cli]>=1.28,<2

Instalación y configuración

1. Clonar el repositorio

git clone https://github.com/moazhassan751/mcp-todo-server.git
cd mcp-todo-server

2. Crear un entorno virtual

# Linux/macOS
python3 -m venv .venv
source .venv/bin/activate

# Windows
python -m venv .venv
.venv\Scripts\activate

3. Instalar dependencias

pip install -r requirements.txt

Modos de ejecución

Ejecución estándar (stdio)

Ejecute el servidor directamente para producción o integración con el host MCP:

python server.py

Inspección para desarrolladores (Inspector MCP)

El Inspector MCP proporciona una interfaz interactiva basada en navegador para probar herramientas, inspeccionar esquemas y simular solicitudes:

mcp dev server.py

El inspector se iniciará y proporcionará una URL de interfaz local (normalmente http://localhost:6274).

Guía de integración con clientes

Para conectar el Servidor Todo MCP a su entorno de IA preferido, configure el servidor en el archivo de configuración MCP de su cliente.

Claude Desktop

Edite el archivo de configuración de Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "todo-server": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-todo-server/server.py"]
    }
  }
}

Cursor

Agregue a .cursor/mcp.json en el directorio de su proyecto o global:

{
  "mcpServers": {
    "todo-server": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-todo-server/server.py"]
    }
  }
}

IDE Antigravity

Agregue a .agents/mcp_config.json en su espacio de trabajo:

{
  "mcpServers": {
    "todo-server": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-todo-server/server.py"]
    }
  }
}

Pruebas y verificación

El repositorio incluye scripts de prueba automatizados completos:

Suite de pruebas estándar

Prueba las llamadas básicas a herramientas, las validaciones de parámetros y el formato de salida:

python test_server.py

Prueba de auditoría multi-sesión

Simula conexiones de clientes separadas, reinicia el proceso del servidor entre sesiones y valida que el almacenamiento persistente conserve correctamente el estado:

python audit_test.py

Estructura del proyecto

mcp-todo-server/
├── server.py           # Core MCP server definition and tool implementations
├── test_server.py      # Automated stdio protocol unit tests
├── audit_test.py       # Multi-session persistence and edge-case verification
├── requirements.txt    # Package dependencies
├── .gitignore          # Version control ignore definitions
└── README.md           # Technical documentation and integration reference

Licencia

Este proyecto es de código abierto y está disponible bajo la Licencia MIT.