Super Productivity MCP

Dale a tu asistente de IA acceso real a tus tareas — sin renunciar a lo local-primero.

Un servidor MCP que lee y escribe tus tareas de Super Productivity a través del archivo de sincronización que ya está en tu Nextcloud. Sin plugin, sin fork, sin una segunda aplicación que mantener al día.

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

Por qué existe esto

Super Productivity es deliberadamente local-primero. No hay API remota, no hay webhook saliente, y la API REST local de la aplicación de escritorio se vincula a 127.0.0.1 — inalcanzable desde cualquier otro lugar por diseño. El plugin CalDAV exporta solo tareas que ya tienen una fecha, y las exporta como eventos de calendario, no como tareas.

El archivo de sincronización es diferente. Contiene todo: cada proyecto, cada etiqueta, todo el backlog sin fecha, subtareas, estimaciones, seguimiento de tiempo. Ya está en tu servidor. Es la imagen completa, y nada más lo es.

Así que este servidor habla con eso.

Related MCP server: Nextcloud MCP Server

Qué lo hace seguro

La versión ingenua de esta idea — descargar el JSON, editarlo, subirlo — eventualmente destruirá tu historial de tareas. Super Productivity no es un archivo con tareas dentro; es un registro de operaciones con relojes vectoriales, y tus dispositivos fusionan cambios reproduciendo operaciones, no comparando archivos.

Este servidor participa en ese protocolo correctamente. Se comporta como un dispositivo más en tu cuenta:

Concretamente, cada escritura:

1. Lee con un ETag fuerte. El OC-ETag de Nextcloud, que sobrevive a los proxies inversos que reescriben el ETag simple.

2. Aplica el cambio a través de un puerto fiel de los propios reducers de Super Productivity — así que TODAY sigue siendo una etiqueta virtual, dueDay y dueWithTime siguen siendo mutuamente excluyentes, y completar una tarea nunca inventa una fecha de vencimiento.

3. Emite la operación correspondiente con el id de cliente de este servidor y un reloj vectorial incrementado, para que tus otros dispositivos lo acepten como causalmente más nuevo en lugar de marcarlo como conflicto.

4. Actualiza el .bak antes de tocar el archivo principal.

5. Escribe condicionalmente, en la revisión que leyó. Nunca incondicionalmente. Si otro dispositivo escribió primero, toda la mutación se re-ejecuta contra el estado fresco — su cambio sobrevive, el tuyo se aplica encima.

Verificado contra un Nextcloud en vivo: If-Match se aplica genuinamente, y después de un ciclo completo de crear/programar/completar/eliminar, el remoto sigue siendo un sobre válido de esquema 4 con archivos y estado intacto byte-por-byte.

Inicio rápido

Requisitos: Node 20.11+, un Nextcloud con Super Productivity ya sincronizando con él.

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

Rellena .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

Usa una contraseña de aplicación, no tu contraseña de inicio de sesión: Configuración → Seguridad → Dispositivos y sesiones → Crear nueva contraseña de aplicación. Está limitada, es revocable, y es lo único que funciona cuando la autenticación de dos factores está activada.

Comprueba todo antes de conectarlo a cualquier cosa:

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.

El doctor nunca escribe. Si un paso falla, dice cuál y por qué — que es el objetivo de tenerlo, porque cada modo de fallo aquí se muestra de otra manera dentro de tu cliente de IA como un "la herramienta no funcionó" poco útil.

Luego construye:

npm run build

Conectándolo

Añade a tu configuración de servidor 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"
      }
    }
  }
}

Puedes omitir env por completo y dejar que lea el archivo .env en su lugar — establece SP_ENV_FILE a una ruta absoluta si el directorio de trabajo no será la raíz del proyecto.

Misma forma, en claude_desktop_config.json (~/Library/Application Support/Claude/ en macOS, %APPDATA%\Claude\ en Windows).

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

Es un servidor MCP estándar de stdio. Ejecuta node dist/main.js; habla JSON-RPC en stdout y registra solo en stderr.

Herramientas

Lectura

Escritura

Diagnóstico

En SP_MODE=read-only las herramientas de escritura no se anuncian en absoluto, en lugar de anunciarse y rechazarse. Una herramienta que un modelo puede ver es una herramienta que intentará.

Dos cosas que vale la pena saber

"Hoy" no es una etiqueta que apliques. Una tarea está en Hoy porque su fecha de vencimiento es hoy. sp_plan_for_today es la forma de ponerla allí; la lista de tareas de la etiqueta TODAY solo almacena el orden.

Las duraciones están en minutos. Super Productivity almacena milisegundos; este servidor convierte en el límite para que nada esté nunca desviado por un factor de sesenta.

Configuración

Los nombres heredados nextcloud_user / nextcloud_password también se aceptan, así que un .env existente no necesita renombrarse.

Por qué se analiza el archivo .env en lugar de ejecutarlo: las contraseñas de aplicación rutinariamente comienzan con $, y source .env en un shell expande $Nyd0… a la cadena vacía. El fallo resultante se ve exactamente como una contraseña incorrecta. Este servidor lee el archivo literalmente y evita toda esa clase de confusión.

Cómo funciona

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

La regla de dependencia apunta hacia adentro: domain no sabe nada de WebDAV o MCP. Eso no es decoración — es por lo que la suite de integración puede ejecutar la totalidad del stack, incluida la lógica de reintento de escritura condicional, contra un almacén en memoria con un reloj congelado, sin conexión, en menos de dos segundos.

Ambos diseños de sincronización, detectados automáticamente

Super Productivity ha enviado dos diseños remotos, y puede migrar una carpeta en cualquier momento:

• Archivo único — sync-data.json contiene la instantánea, archivos y registro juntos. El predeterminado.

• Dividido — sync-ops.json es el punto de confirmación, sync-state.json la instantánea. Opt-in ("Sincronización quirúrgica").

El diseño se detecta en cada lectura, nunca se configura. En el diseño dividido, la instantánea solo se reescribe en la compactación, por lo que puede retrasarse hasta 2000 operaciones; este servidor reproduce el registro pendiente para cerrar la brecha y informa de cualquier cosa que no haya podido reproducir en lugar de mostrarte silenciosamente una imagen incompleta.

Cifrado

Si habilitaste el cifrado en Super Productivity, establece SP_ENCRYPTION_PASSWORD con la misma contraseña. La canalización — JSON → gzip → AES-256-GCM derivado de Argon2id — coincide exactamente con la versión original, incluido el formato PBKDF2 heredado para archivos escritos por clientes antiguos.

Un archivo en texto plano es rechazado cuando el cifrado está configurado. La marca de cifrado vive fuera del sobre autenticado, por lo que cualquiera que pueda escribir en tu remoto podría eliminarla y servirte sus propios datos; la intención local prevalece sobre la autodeclaración del remoto.

Desarrollo

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 pruebas. La suite de integración ejecuta toda la pila contra un almacén en memoria que evalúa If-Match de verdad, cubriendo las situaciones que de otro modo son casi imposibles de preparar: un dispositivo rival confirmando dentro de la brecha de lectura-escritura, un servidor sin ETags utilizables, una escritura de copia de seguridad fallida, una carpeta con tombstone, un remoto corrupto.

El fixture de prueba es un archivo de sincronización real — mismo sobre, mismo registro de 344 operaciones, misma versión de esquema — con cada título y nota reemplazados por texto sintético.

De extremo a extremo

npm run test:e2e se ejecuta contra un Nextcloud real, en una carpeta de sandbox separada sembrada a partir de una copia de tu archivo de sincronización y eliminada después. Tu carpeta de sincronización real nunca es escrita por la suite. Se omite a sí misma cuando no hay credenciales configuradas.

Establece SP_E2E_FOLDER en .env (por defecto super-productivity-mcp-e2e). Debe diferir de SP_SYNC_FOLDER; la suite crea, sobrescribe y elimina archivos dentro de ella.

Limitaciones

Dicho claramente, porque la alternativa es descubrirlas más tarde:

• La sincronización no es instantánea. Los cambios llegan al archivo de sincronización inmediatamente; tu escritorio y tu teléfono los recogen en su próxima sincronización.

• Las tareas archivadas son de solo lectura. Este servidor lee tus archivos pero nunca escribe en ellos. Completa las tareas en lugar de archivarlas.

• El diseño dividido es de solo añadir. Cuando su registro de operaciones se llena, el servidor rechaza más escrituras y te dice que abras Super Productivity una vez para que pueda compactar. Compactar significaría publicar una instantánea parcialmente reproducida como autoritativa, lo que podría descartar silenciosamente lo que no logró reproducir.

• Sin seguimiento de tiempo ni Pomodoro. Esas son funciones locales y en vivo; no hay nada sensato que escribir desde aquí.

• Las notas y las tareas repetitivas son de solo lectura, no escribibles.

• Un nivel de anidamiento de subtareas, igual que Super Productivity.

Solución de problemas

Créditos

Construido sobre Super Productivity por Johannes Millan. El formato de registro de operaciones, los algoritmos de reloj vectorial y la semántica del reductor aquí son puertos de la implementación de ese proyecto — consulta docs/sync-and-op-log/ para la arquitectura que este servidor tuvo que aprender a hablar.

Licencia

MIT