Super Productivity MCP

Дайте вашему ИИ-ассистенту реальный доступ к вашим задачам — не отказываясь от локального хранения.

MCP-сервер, который читает и записывает ваши задачи Super Productivity через файл синхронизации, уже лежащий в вашем Nextcloud. Без плагина, без форка, без второго приложения, которое нужно поддерживать в актуальном состоянии.

┌─────────────────┐         ┌──────────────────┐         ┌─────────────────┐
│  Super          │  sync   │    Nextcloud     │  sync   │  This MCP       │
│  Productivity   │ ──────► │  sync-data.json  │ ◄────── │  server         │
│  desktop/mobile │ ◄────── │                  │ ──────► │                 │
└─────────────────┘         └──────────────────┘         └────────┬────────┘
                                                                  │ MCP
                                                         ┌────────▼────────┐
                                                         │  OpenClaw,      │
                                                         │  Claude, …      │
                                                         └─────────────────┘

Зачем это существует

Super Productivity намеренно ориентирован на локальное хранение. Нет удалённого API, нет исходящих вебхуков, а локальный REST API десктопного приложения привязан к 127.0.0.1 — недоступен ниоткуда по дизайну. Плагин CalDAV экспортирует только задачи, у которых уже есть дата, и экспортирует их как календарные события, а не задачи.

Файл синхронизации — другое дело. В нём хранится всё: каждый проект, каждый тег, весь недатированный бэклог, подзадачи, оценки, учёт времени. Он уже есть на вашем сервере. Это полная картина, и больше ничего такого нет.

Поэтому этот сервер работает с ним.

Related MCP server: Nextcloud MCP Server

Что делает его безопасным

Наивная версия этой идеи — скачать JSON, отредактировать, загрузить — в конечном счёте разрушит историю ваших задач. Super Productivity — это не файл с задачами; это журнал операций с векторными часами, и ваши устройства объединяют изменения, воспроизводя операции, а не сравнивая файлы.

Этот сервер корректно участвует в этом протоколе. Он ведёт себя как ещё одно устройство в вашей учётной записи:

Конкретно, каждая запись:

1. Читает с сильным ETag. OC-ETag от Nextcloud, который переживает переписывание обычного ETag обратными прокси.

2. Применяет изменение через точный порт собственных редьюсеров Super Productivity — так что TODAY остаётся виртуальным тегом, dueDay и dueWithTime остаются взаимоисключающими, а завершение задачи никогда не выдумывает дату выполнения.

3. Генерирует соответствующую операцию с client id этого сервера и увеличенными векторными часами, чтобы другие ваши устройства приняли её как причинно более новую, а не пометили как конфликт.

4. Обновляет .bak перед тем, как трогать основной файл.

5. Записывает условно, на той ревизии, которую прочитал. Никогда безусловно. Если другое устройство записало первым, вся мутация повторно выполняется против свежего состояния — их изменение сохраняется, ваше применяется поверх.

Проверено на живом Nextcloud: If-Match действительно соблюдается, и после полного цикла создание/планирование/завершение/удаление удалённый файл остаётся валидным конвертом schema-4 с архивами и нетронутым состоянием, байт-в-байт идентичным.

Быстрый старт

Требования: Node 20.11+, Nextcloud с уже синхронизирующимся Super Productivity.

git clone <this-repo> superproductivity-mcp
cd superproductivity-mcp
npm install
cp .env.example .env

Заполните .env:

SP_NEXTCLOUD_URL=https://cloud.example.com
SP_NEXTCLOUD_USER=yourname
SP_NEXTCLOUD_PASSWORD=xxxxx-xxxxx-xxxxx-xxxxx-xxxxx
SP_SYNC_FOLDER=super-productivity

Используйте пароль приложения, а не пароль для входа: Настройки → Безопасность → Устройства и сеансы → Создать пароль приложения. Он ограничен, отзываемый, и это единственное, что работает при включённой двухфакторной аутентификации.

Проверьте всё перед подключением к чему-либо:

npm run doctor

Super Productivity MCP — doctor (v1.0.0)

  ok   configuration                https://cloud.example.com as yourname
  ok   sync folder                  super-productivity
  ok   mode                         read-write
  ok   client id                    M_TSrPmbHAoq
  ok   encryption                   not configured (the sync file must be plaintext)
  ok   reachable                    Nextcloud answered and the credentials were accepted
  ok   sync file                    SINGLE_FILE (sync-data.json)
  ok   decoded                      syncVersion 114, schema 4
  ok   conditional writes           the server returns a strong ETag, so concurrent writes are safe
  ok   devices                      B_UjDTUW, A_rmkezu
  ok   operation log                354 of 2000 retained
  ok   contents                     12 open tasks, 3 projects, 4 tags

All checks passed. The MCP server should work.

Доктор никогда не пишет. Если шаг не удался, он сообщает, какой именно и почему — в этом весь смысл его существования, потому что каждый режим отказа здесь иначе проявляется внутри вашего ИИ-клиента как бесполезное «инструмент не сработал».

Затем соберите:

npm run build

Подключение

Добавьте в конфигурацию вашего MCP-сервера:

{
  "mcpServers": {
    "superproductivity": {
      "command": "node",
      "args": ["/absolute/path/to/superproductivity-mcp/dist/main.js"],
      "env": {
        "SP_NEXTCLOUD_URL": "https://cloud.example.com",
        "SP_NEXTCLOUD_USER": "yourname",
        "SP_NEXTCLOUD_PASSWORD": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx",
        "SP_SYNC_FOLDER": "super-productivity"
      }
    }
  }
}

Вы можете полностью опустить env и позволить ему читать файл .env — установите SP_ENV_FILE в абсолютный путь, если рабочая директория не будет корнем проекта.

Та же форма, в claude_desktop_config.json (~/Library/Application Support/Claude/ на macOS, %APPDATA%\Claude\ на Windows).

claude mcp add superproductivity -- node /absolute/path/to/dist/main.js

Это стандартный stdio MCP-сервер. Запустите node dist/main.js; он говорит на JSON-RPC в stdout и пишет логи только в stderr.

Инструменты

Чтение

Запись

Диагностика

В SP_MODE=read-only инструменты записи вообще не рекламируются, а не рекламируются и отклоняются. Инструмент, который модель видит, — это инструмент, который она попробует.

Две вещи, которые стоит знать

«Сегодня» — это не тег, который вы применяете. Задача находится в «Сегодня», потому что её срок — сегодня. sp_plan_for_today — это способ поместить её туда; список задач тега TODAY хранит только порядок.

Длительность в минутах. Super Productivity хранит миллисекунды; этот сервер конвертирует на границе, чтобы ничего никогда не отличалось в шестьдесят раз.

Конфигурация

Устаревшие имена nextcloud_user / nextcloud_password также принимаются, так что существующему .env не нужно переименование.

Почему файл .env разбирается, а не подключается: пароли приложений часто начинаются с $, и source .env в оболочке разворачивает $Nyd0… в пустую строку. Возникающий сбой выглядит точно как неверный пароль. Этот сервер читает файл буквально и обходит весь класс путаницы.

Как это работает

src/
├── domain/          Pure. No I/O, no framework, no network.
│   ├── model/         Super Productivity's state, as we read it
│   ├── reducers/      Faithful ports of upstream's own reducers
│   ├── sync/          Vector clocks, the compact operation format
│   ├── errors.ts      One taxonomy, split by what the caller should do
│   └── ports.ts       The boundary: FileStore, Clock, IdGenerator, Logger
├── application/     Use cases and projections
│   ├── workspace.ts   Read-modify-write with optimistic concurrency
│   ├── read-models.ts Raw state → something a model can act on
│   └── services/      Task, organiser and diagnostics use cases
├── infrastructure/  Everything that touches the outside world
│   ├── codec/         The pf_ prefix, gzip, Argon2id + AES-GCM
│   ├── webdav/        Conditional writes, strong validators
│   ├── sync/          Layout detection, operation replay
│   └── config/        Env loading and validation
├── presentation/    The MCP tool surface
└── composition-root.ts  The only place a concrete dependency is chosen

Правило зависимостей направлено внутрь: domain ничего не знает о WebDAV или MCP. Это не украшение — это причина, по которой интеграционный набор может запускать весь стек, включая логику повторных условных записей, против хранилища в памяти с замороженными часами, офлайн, менее чем за две секунды.

Обе раскладки синхронизации, определяемые автоматически

Super Productivity выпускал две удалённые раскладки и может мигрировать папку в любое время:

• Один файл — sync-data.json содержит снимок, архивы и журнал вместе. По умолчанию.

• Раздельно — sync-ops.json — точка фиксации, sync-state.json — снимок. По желанию («Хирургическая синхронизация»).

Макет определяется при каждом чтении и никогда не настраивается. В разделённом макете снимок перезаписывается только при уплотнении, поэтому он может отставать на целых 2000 операций; этот сервер воспроизводит ожидающий журнал, чтобы закрыть разрыв, и сообщает обо всём, что не смог воспроизвести, вместо того чтобы молча показывать вам неполную картину.

Шифрование

Если вы включили шифрование в Super Productivity, задайте SP_ENCRYPTION_PASSWORD равным тому же паролю. Конвейер — JSON → gzip → AES-256-GCM на основе Argon2id — полностью совпадает с исходным, включая устаревший формат PBKDF2 для файлов, записанных старыми клиентами.

Обычный текстовый файл отклоняется, когда настроено шифрование. Флаг шифрования находится вне аутентифицированной оболочки, поэтому любой, кто может писать в ваш удалённый репозиторий, может снять его и подсунуть вам собственные данные; локальное намерение имеет приоритет над самодекларацией удалённой стороны.

Разработка

npm test              # unit + integration, no network, ~2s
npm run test:unit
npm run test:integration
npm run test:coverage
npm run test:e2e      # real Nextcloud — see below
npm run verify        # format + lint + typecheck + test
npm run dev           # run from source

284 теста. Интеграционный набор запускает весь стек против хранилища в памяти, которое по-настоящему вычисляет If-Match, охватывая ситуации, которые иначе почти невозможно воспроизвести: конкурирующее устройство, выполняющее запись в разрыве чтения-записи, сервер без пригодных ETag, неудачная запись резервной копии, папка с tombstone, повреждённый удалённый репозиторий.

Тестовый фикстур — это настоящий файл синхронизации — та же оболочка, тот же журнал из 344 операций, та же версия схемы — где каждый заголовок и заметка заменены синтетическим текстом.

Сквозное тестирование

npm run test:e2e запускается против настоящего Nextcloud, в отдельной песочнице, заполняемой из копии вашего файла синхронизации и удаляемой после завершения. Ваша настоящая папка синхронизации никогда не записывается набором. Он пропускает себя, когда учётные данные не настроены.

Задайте SP_E2E_FOLDER в .env (по умолчанию super-productivity-mcp-e2e). Он должен отличаться от SP_SYNC_FOLDER; набор создаёт, перезаписывает и удаляет файлы внутри него.

Ограничения

Изложено прямо, потому что альтернатива — обнаружить их позже:

• Синхронизация не мгновенна. Изменения попадают в файл синхронизации немедленно; ваш компьютер и телефон подхватывают их при следующей синхронизации.

• Архивированные задачи доступны только для чтения. Этот сервер читает ваши архивы, но никогда не пишет в них. Завершайте задачи вместо архивирования.

• Разделённый макет — только добавление. Когда журнал операций заполняется, сервер отказывает в дальнейших записях и сообщает вам открыть Super Productivity один раз, чтобы он мог выполнить уплотнение. Уплотнение означало бы публикацию частично воспроизведённого снимка как авторитетного, что могло бы молча отбросить то, что не удалось воспроизвести.

• Нет учёта времени или Pomodoro. Это локальные, живые функции; отсюда нет ничего разумного, что можно было бы записать.

• Заметки и повторяющиеся задачи — сквозное чтение, не записываемые.

• Один уровень вложенности подзадач, как и в самом Super Productivity.

Устранение неполадок

Благодарности

Создано на основе Super Productivity Йоханнеса Миллана. Формат журнала операций, алгоритмы векторных часов и семантика редьюсера здесь — это порты реализации самого проекта — см. docs/sync-and-op-log/ для описания архитектуры, на которой этому серверу пришлось научиться говорить.

Лицензия

MIT