🚀 DoneTick MCP Server (Model Context Protocol SSE)

Полный, готовый к продакшену Model Context Protocol (MCP) сервер, реализующий HTTP Server-Sent Events (SSE) для DoneTick (самостоятельно размещаемое управление задачами и поручениями).

Совместим с Mistral Le Chat, Claude Desktop, LibreChat, n8n, Open WebUI и любым MCP-клиентом.

📋 Возможности

Сервер предоставляет 57 специализированных MCP-инструментов, покрывающих API DoneTick, включая историю выполнения и отслеживание времени. Каждая конечная точка проверяется на живом экземпляре с помощью npm run smoke.

1. 📝 Поручения и задачи (donetick_*)

• donetick_list_chores: Список задач с фильтрами (поиск, проект, статус).

• donetick_get_chore: Полные детали задачи — повторение, исполнители, подзадачи, метки, триггеры — плюс lastCompletedDate, lastCompletedBy и timeSpentSeconds.

• donetick_create_chore: Создание поручения с датой выполнения, повторением, приоритетом, баллами, проектом, подзадачами, метками, уведомлениями, утверждением и сенсорными триггерами.

• donetick_update_chore: Частичное или полное обновление. Прерывается, а не записывает вслепую, если поручение не удалось сначала прочитать.

• donetick_complete_chore: Завершить поручение и запланировать следующее повторение.

• donetick_undo_chore: Отменить последнее завершение.

• donetick_delete_chore: Безвозвратно удалить поручение (предпочтительнее архивирование).

• donetick_set_due_date: Установить, изменить или очистить дату выполнения.

• donetick_set_priority: Установить приоритет — 1 — самый высокий (P1), 4 — самый низкий, 0 — нет.

• donetick_skip_chore: Пропустить текущее повторение.

• donetick_nudge_chore: Отправить напоминание исполнителю.

• donetick_set_chore_notifications: Настроить напоминания (дата выполнения, предварительное, назойливое, завершение).

• donetick_set_chore_project, donetick_set_chore_assignee: Переназначить поручение.

2. 📊 История выполнения (donetick_*)

• donetick_get_chore_history: Каждое завершение, пропуск, перенос и пропуск для одного поручения, с читаемым statusName и сводкой. Это единственный надёжный способ отличить «выполнено» от «отредактировано» — updatedAt смешивает оба.

• donetick_get_history: Активность по кругу, фильтруемая по диапазону дат и статусу.

• donetick_modify_history_entry: Исправить, когда было зарегистрировано завершение, или его заметки.

• donetick_delete_history_entry: Удалить ошибочную запись.

3. ⏱️ Отслеживание времени (donetick_*)

• donetick_start_chore / donetick_pause_chore: Запуск таймера для поручения.

• donetick_get_chore_timer: Общее затраченное время плюс каждая рабочая сессия.

• donetick_reset_chore_timer: Сбросить накопленное время.

• donetick_adjust_time_session / donetick_delete_time_session: Исправить историю задним числом.

4. 🧩 Подзадачи (donetick_*)

• donetick_set_subtasks: Заменить весь список. Деструктивно, но сохраняет идентификаторы и состояние выполнения, сопоставляя по имени.

• donetick_add_subtask: Добавить одну подзадачу, оставив остальные нетронутыми.

• donetick_complete_subtask / donetick_uncomplete_subtask: Отметить одну подзадачу по идентификатору или имени.

• donetick_remove_subtask: Удалить одну подзадачу без перезаписи списка.

Примечание: завершение повторяющегося поручения очищает его подзадачи, а не отмечает их. Это собственное поведение DoneTick, подготавливающее следующее вхождение.

5. 🗄️ Архивирование и утверждение (donetick_*)

• donetick_list_archived_chores, donetick_archive_chore, donetick_unarchive_chore: Обратимая альтернатива удалению.

• donetick_approve_chore, donetick_reject_chore: Проверка завершений для поручений с requireApproval.

6. 🏷️ Метки и теги (donetick_*)

• donetick_list_labels: Список меток с запасным вариантом извлечения их из поручений.

• donetick_create_label, donetick_update_label, donetick_delete_label: См. ограничение ниже — для них требуется JWT.

• donetick_set_chore_labels, donetick_add_chore_label: Прикрепить метки к поручению.

7. ⚡ Умные вещи и триггеры событий (donetick_*)

• donetick_list_things, donetick_create_thing, donetick_update_thing, donetick_delete_thing.

• donetick_set_thing_state: Обновить датчик или счётчик, автоматически запуская связанные задачи.

• donetick_get_thing_history: Каждое состояние, которое принимала вещь, и когда.

• donetick_link_thing_chore / donetick_unlink_thing_chore: Условия триггера (eq, neq, gt, lt, gte, lte).

8. 📁 Проекты (donetick_*)

• donetick_list_projects, donetick_create_project, donetick_update_project, donetick_delete_project.

9. 👥 Круги, участники и фильтры (donetick_*)

• donetick_get_circle_info, donetick_list_members, donetick_list_filters.

Related MCP server: Deferno MCP Server

📅 Даты и приоритеты

Даты. DoneTick привязывает каждую дату к Go time.Time, поэтому принимает только RFC3339. Коннектор дополнительно принимает YYYY-MM-DD и YYYY-MM-DD HH:mm, разрешая их в DONETICK_TIMEZONE (по умолчанию UTC) в DONETICK_DEFAULT_DUE_TIME (по умолчанию 18:00). Установите оба, если хотите, чтобы «выполнить завтра» означало разумный локальный час, а не полночь по UTC.

Приоритеты. DoneTick считает вниз: 1 — самый высокий приоритет, отображается как красный P1 в веб-интерфейсе, а 4 — самый низкий; 0 означает отсутствие приоритета. Версии до 2.0.0 документировали это наоборот, поэтому поручения, созданные через старые описания, могут содержать инвертированные значения.

⚠️ Известные ограничения

• Метки нельзя создавать или редактировать с помощью API-ключа. DoneTick монтирует /api/v1/labels за промежуточным ПО, требующим только JWT, в отличие от всех других маршрутов. Чтение возвращается к извлечению меток из поручений; управляйте ими в веб-интерфейсе.

• Нельзя записать произвольную длительность. POST /chores/{id}/do не принимает значение затраченного времени, а обработчик ручной длительности DoneTick определён, но никогда не маршрутизируется. Используйте запуск/паузу или корректируйте границы сессии задним числом.

• Окна истории в днях. limit в DoneTick — это количество дней, а не строк; since/until применяются на стороне клиента после выборки.

🔒 Безопасность и усиление OWASP

• OWASP A01 и A07 (Контроль доступа и атаки по времени): Постоянное по времени сравнение токенов аутентификации (crypto.timingSafeEqual).

• OWASP A02 (Криптографические сбои и утечка информации): Редактирование секретов в журналах и безопасная телеметрия /health без учётных данных.

• OWASP A03 (Инъекции и SSRF): Строгая санитизация протоколов (http:, https:) для предотвращения инъекций протоколов или SSRF (file://, gopher://).

• OWASP A04 (Отказ в обслуживании): Строгие ограничения размера тела JSON (1mb) и активные лимиты SSE-сессий с обрезкой соединений.

• OWASP A05 (Неправильная конфигурация безопасности): Усиленные HTTP-заголовки (X-Content-Type-Options: nosniff, X-Frame-Options: DENY, X-XSS-Protection: 0, Referrer-Policy: no-referrer, X-Powered-By отключён). Выполнение Docker от непривилегированного пользователя (USER node).

🐳 Быстрый старт с Docker

1. Создайте 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. Запустите контейнер

docker compose up -d

🤖 Подключение к Mistral Le Chat

1. В Mistral Le Chat перейдите в Настройки ➔ Инструменты и MCP (или Коннекторы).

2. Нажмите «Добавить MCP-сервер».

3. Заполните настройки подключения:

   • Имя: DoneTick

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

   • Аутентификация: Bearer Token

   • Токен: <Ваш API-токен DoneTick> (создаётся в DoneTick ➔ Настройки ➔ API-токен)

4. Сохраните и начните общение!

Примеры запросов:

• «Какие поручения просрочены или должны быть выполнены сегодня?»

• «Создай поручение "Почистить эспрессо-машину" на следующее воскресенье с высоким приоритетом и подзадачами: "Промыть группу", "Удалить накипь из котла".»

• «Привяжи поручение #21 к моему счётчику кофе (Вещь #11), чтобы срабатывало, когда счётчик >= 100.»

• «Отметь задачу #5 как выполненную с 20 баллами.»

🧪 Разработка и тестирование

# 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

Живой смоук-тест

Модульный набор тестов имитирует axios, поэтому он доказывает, что полезные нагрузки сформированы правильно — но не то, что DoneTick их принимает. Перед выпуском релиза запустите смоук-тест на реальном экземпляре:

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

Он создаёт только объекты с префиксом [mcp-test], проверяет каждую конечную точку, используемую коннектором, удаляет созданное и отказывается удалять что-либо без этого префикса. Существующие поручения никогда не изменяются.

📄 Лицензия

Лицензия MIT. Не стесняйтесь использовать, изменять и распространять.