🚀 DoneTick MCP Server (Model Context Protocol SSE)

Un servidor Model Context Protocol (MCP) completo y listo para producción que implementa HTTP Server-Sent Events (SSE) para DoneTick (gestión de quehaceres y tareas autoalojada).

Compatible con Mistral Le Chat, Claude Desktop, LibreChat, n8n, Open WebUI y cualquier cliente MCP.

📋 Características

El servidor proporciona 57 herramientas MCP especializadas que cubren la API de DoneTick, incluidos el historial de finalización y el seguimiento de tiempo. Cada endpoint se verifica contra una instancia en vivo mediante npm run smoke.

1. 📝 Quehaceres y tareas (donetick_*)

• donetick_list_chores: Lista tareas con filtros (búsqueda, proyecto, estado).

• donetick_get_chore: Detalles completos de la tarea: recurrencia, asignados, subtareas, etiquetas, disparadores, además de lastCompletedDate, lastCompletedBy y timeSpentSeconds.

• donetick_create_chore: Crea un quehacer con fecha de vencimiento, recurrencia, prioridad, puntos, proyecto, subtareas, etiquetas, notificaciones, aprobación y disparadores de sensores.

• donetick_update_chore: Actualizaciones parciales o completas. Se aborta en lugar de escribir a ciegas si el quehacer no se puede leer primero.

• donetick_complete_chore: Completa un quehacer y programa su próxima recurrencia.

• donetick_undo_chore: Deshace la última finalización.

• donetick_delete_chore: Elimina permanentemente un quehacer (prefiere archivar).

• donetick_set_due_date: Establece, cambia o borra una fecha de vencimiento.

• donetick_set_priority: Establece la prioridad: 1 es la más alta (P1), 4 la más baja, 0 ninguna.

• donetick_skip_chore: Omite la recurrencia actual.

• donetick_nudge_chore: Envía un recordatorio al asignado.

• donetick_set_chore_notifications: Configura recordatorios (fecha de vencimiento, previo al vencimiento, insistencia, finalización).

• donetick_set_chore_project, donetick_set_chore_assignee: Reasigna un quehacer.

2. 📊 Historial de finalización (donetick_*)

• donetick_get_chore_history: Cada finalización, omisión, reprogramación y fallo de un quehacer, con un statusName legible y un resumen. Esta es la única forma fiable de distinguir "hecho" de "editado": updatedAt los confunde.

• donetick_get_history: Actividad de todo el círculo, filtrable por rango de fechas y estado.

• donetick_modify_history_entry: Corrige cuándo se registró una finalización o sus notas.

• donetick_delete_history_entry: Elimina una entrada errónea.

3. ⏱️ Seguimiento de tiempo (donetick_*)

• donetick_start_chore / donetick_pause_chore: Ejecuta el temporizador por quehacer.

• donetick_get_chore_timer: Tiempo total invertido más cada sesión de trabajo.

• donetick_reset_chore_timer: Borra el tiempo acumulado.

• donetick_adjust_time_session / donetick_delete_time_session: Corrige el historial a posteriori.

4. 🧩 Subtareas (donetick_*)

• donetick_set_subtasks: Reemplaza toda la lista. Destructivo, pero conserva los ids y el estado de finalización al coincidir por nombre.

• donetick_add_subtask: Añade una subtarea, dejando las demás intactas.

• donetick_complete_subtask / donetick_uncomplete_subtask: Marca una subtarea, por id o por nombre.

• donetick_remove_subtask: Elimina una subtarea sin reescribir la lista.

Nota: completar un quehacer recurrente borra sus subtareas en lugar de marcarlas. Ese es el comportamiento propio de DoneTick, preparando la siguiente ocurrencia.

5. 🗄️ Archivado y aprobación (donetick_*)

• donetick_list_archived_chores, donetick_archive_chore, donetick_unarchive_chore: Alternativa reversible a la eliminación.

• donetick_approve_chore, donetick_reject_chore: Revisa las finalizaciones en quehaceres con requireApproval.

6. 🏷️ Etiquetas y tags (donetick_*)

• donetick_list_labels: Lista etiquetas, recurriendo a extraerlas de los quehaceres si es necesario.

• donetick_create_label, donetick_update_label, donetick_delete_label: Consulta la limitación a continuación: requieren un JWT.

• donetick_set_chore_labels, donetick_add_chore_label: Adjunta etiquetas a un quehacer.

7. ⚡ Cosas inteligentes y disparadores de eventos (donetick_*)

• donetick_list_things, donetick_create_thing, donetick_update_thing, donetick_delete_thing.

• donetick_set_thing_state: Actualiza un sensor o contador, disparando automáticamente las tareas vinculadas.

• donetick_get_thing_history: Cada estado que una cosa ha tenido, y cuándo.

• donetick_link_thing_chore / donetick_unlink_thing_chore: Condiciones de disparo (eq, neq, gt, lt, gte, lte).

8. 📁 Proyectos (donetick_*)

• donetick_list_projects, donetick_create_project, donetick_update_project, donetick_delete_project.

9. 👥 Círculos, miembros y filtros (donetick_*)

• donetick_get_circle_info, donetick_list_members, donetick_list_filters.

Related MCP server: Yandex Tracker MCP

📅 Fechas y prioridades

Fechas. DoneTick vincula cada fecha a un time.Time de Go, por lo que solo acepta RFC3339. El conector además acepta YYYY-MM-DD y YYYY-MM-DD HH:mm, resolviéndolos en DONETICK_TIMEZONE (por defecto UTC) a las DONETICK_DEFAULT_DUE_TIME (por defecto 18:00). Establece ambos si quieres que "que vence mañana" signifique una hora local razonable en lugar de la medianoche UTC.

Prioridades. DoneTick cuenta hacia abajo: 1 es la prioridad más alta, mostrada como un P1 rojo en la interfaz web, y 4 es la más baja; 0 significa sin prioridad. Las versiones anteriores a 2.0.0 documentaban esto al revés, por lo que los quehaceres creados con las descripciones antiguas pueden tener valores invertidos.

⚠️ Limitaciones conocidas

• Las etiquetas no se pueden crear ni editar con una clave de API. DoneTick monta /api/v1/labels detrás de un middleware solo JWT, a diferencia de todas las demás rutas. La lectura recurre a extraer etiquetas de los quehaceres; adminístralas en la interfaz web.

• No se puede registrar una duración arbitraria. POST /chores/{id}/do no acepta ningún valor de tiempo invertido, y el manejador de duración manual de DoneTick está definido pero nunca enrutado. Usa iniciar/pausar, o ajusta los límites de una sesión después.

• Las ventanas de historial están en días. El limit de DoneTick es un número de días, no de filas; since/until se aplican en el lado del cliente después de la obtención.

🔒 Seguridad y endurecimiento OWASP

• OWASP A01 y A07 (Control de acceso y ataques de temporización): validación de token de autenticación en tiempo constante (crypto.timingSafeEqual).

• OWASP A02 (Fallos criptográficos y fuga de información): redacción de secretos en registros y telemetría segura de /health sin credenciales.

• OWASP A03 (Inyección y SSRF): saneamiento estricto de protocolo (http:, https:) que previene la inyección de protocolo o SSRF (file://, gopher://).

• OWASP A04 (Denegación de servicio): límites estrictos de carga útil JSON (1mb) y límites de sesiones SSE activas con poda de conexiones.

• OWASP A05 (Configuración de seguridad incorrecta): cabeceras HTTP endurecidas (X-Content-Type-Options: nosniff, X-Frame-Options: DENY, X-XSS-Protection: 0, Referrer-Policy: no-referrer, X-Powered-By deshabilitado). Ejecución de Docker sin root (USER node).

🐳 Inicio rápido con Docker

1. Crea un docker-compose.yml

services:
  mcp-donetick:
    image: ghcr.io/bibiwan/mcp_donetick:latest
    container_name: mcp-donetick
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - PORT=3000
      - HOST=0.0.0.0
      - DONETICK_URL=http://donetick:2021
      - DONETICK_TOKEN=
      # Resolves date-only inputs such as "2026-08-30" to a local hour
      - DONETICK_TIMEZONE=Europe/Paris
      - DONETICK_DEFAULT_DUE_TIME=18:00
      - MCP_AUTH_TOKEN=
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/health"]
      interval: 30s
      timeout: 5s
      retries: 3

2. Lanza el contenedor

docker compose up -d

🤖 Conéctate con Mistral Le Chat

1. En Mistral Le Chat, ve a Configuración ➔ Herramientas y MCP (o Conectores).

2. Haz clic en "Añadir servidor MCP".

3. Completa los ajustes de conexión:

   • Nombre: DoneTick

   • URL: https://<your-server-host>:3000/sse

   • Autenticación: Bearer Token

   • Token: <Your DoneTick API Token> (generado en DoneTick ➔ Configuración ➔ Token de API)

4. ¡Guarda y empieza a chatear!

Ejemplos de indicaciones:

• "¿Qué quehaceres están vencidos o vencen hoy?"

• "Crea un quehacer 'Limpiar máquina de espresso' para el próximo domingo con prioridad alta y subtareas: 'Retrolavado del grupo', 'Descalcificar caldera'."

• "Vincula el quehacer #21 a mi contador de café (Cosa #11) para que se dispare cuando el contador sea >= 100."

• "Marca la tarea #5 como completada con 20 puntos."

🧪 Desarrollo y pruebas

# Install dependencies
npm install

# Run the test suite with coverage.
# Enforces an 80% floor on statements, branches, functions and lines.
npm test

# Build TypeScript
npm run build

# Start local server
npm start

Prueba de humo en vivo

La suite de pruebas unitarias simula axios, por lo que demuestra que los payloads tienen la forma prevista, no que DoneTick los acepte. Antes de etiquetar una versión, ejecuta la prueba de humo contra una instancia real:

DONETICK_URL=https://donetick.example DONETICK_TOKEN=xxx npm run smoke

Crea solo objetos con el prefijo [mcp-test], ejercita cada endpoint que usa el conector, elimina lo que creó y se niega a eliminar cualquier cosa que no tenga ese prefijo. Los quehaceres existentes nunca se modifican.

📄 Licencia

Licencia MIT. Siéntete libre de usar, modificar y distribuir.