Super Productivity MCP

AI 어시스턴트에게 작업에 대한 실제 접근 권한을 부여하세요 — 로컬 우선(local-first) 원칙을 포기하지 않고.

이미 Nextcloud에 있는 동기화 파일을 통해 Super Productivity 작업을 읽고 쓰는 MCP 서버입니다. 플러그인도, 포크도, 따라가야 할 별도 앱도 없습니다.

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

왜 만들었나

Super Productivity는 의도적으로 로컬 우선(local-first)입니다. 원격 API도, 아웃바운드 웹훅도 없으며, 데스크톱 앱의 로컬 REST API는 127.0.0.1에 바인딩되어 있어 — 설계상 다른 어디에서도 접근할 수 없습니다. CalDAV 플러그인은 날짜가 이미 있는 작업만 내보내며, 그것도 작업(task)이 아니라 캘린더 이벤트로 내보냅니다.

동기화 파일은 다릅니다. 그 파일에는 모든 것이 담겨 있습니다: 모든 프로젝트, 모든 태그, 날짜가 없는 전체 백로그, 하위 작업, 예상 시간, 시간 추적. 이미 서버에 있습니다. 그것이 완전한 그림이며, 다른 무엇도 아닙니다.

그래서 이 서버는 그 파일과 통신합니다.

Related MCP server: Nextcloud MCP Server

안전한 이유

이 아이디어의 순진한 버전 — JSON을 다운로드하고, 편집하고, 업로드하는 방식 — 은 결국 작업 기록을 파괴합니다. Super Productivity는 작업이 들어 있는 파일이 아니라 벡터 클록(vector clock)을 가진 작업 로그(operation log) 이며, 여러 기기는 파일을 비교하는 것이 아니라 작업을 재생(replay)하여 변경 사항을 병합합니다.

이 서버는 그 프로토콜에 제대로 참여합니다. 계정의 또 하나의 기기처럼 동작합니다:

구체적으로, 모든 쓰기는:

1. 강력한 ETag로 읽습니다. Nextcloud의 OC-ETag는 일반 ETag를 재작성하는 리버스 프록시를 통과해도 유지됩니다.

2. Super Productivity 자체 리듀서의 충실한 포트를 통해 변경을 적용합니다 — 그래서 TODAY는 가상 태그로 유지되고, dueDay와 dueWithTime은 상호 배타적으로 유지되며, 작업 완료가 마감일을 임의로 만들지 않습니다.

3. 이 서버의 클라이언트 ID와 증가된 벡터 클록으로 일치하는 작업을 내보냅니다. 그래서 다른 기기들이 이를 충돌로 표시하는 대신 인과적으로 더 새로운 것으로 수용합니다.

4. 기본 파일을 건드리기 전에 .bak을 갱신합니다.

5. 읽은 리비전에 대해 조건부로 씁니다. 절대 무조건적으로 쓰지 않습니다. 다른 기기가 먼저 썼다면, 전체 변경이 새 상태에 대해 다시 실행됩니다 — 상대방의 변경은 살아남고, 내 변경은 그 위에 적용됩니다.

실제 Nextcloud에서 검증됨: If-Match가 진짜로 강제되며, 전체 생성/일정 등록/완료/삭제 주기 후에도 원격은 여전히 유효한 스키마-4 봉투(envelope)이며 아카이브와 변경되지 않은 상태가 바이트 단위로 동일합니다.

빠른 시작

요구 사항: Node 20.11+, Super Productivity가 이미 동기화 중인 Nextcloud.

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

로그인 비밀번호가 아닌 앱 비밀번호(app password)를 사용하세요: 설정 → 보안 → 기기 및 세션 → 새 앱 비밀번호 만들기. 범위가 제한되고, 철회 가능하며, 2단계 인증이 켜져 있을 때 유일하게 작동하는 방법입니다.

무엇이든 연결하기 전에 모든 것을 확인하세요:

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.

닥터(doctor)는 절대 쓰지 않습니다. 단계가 실패하면 어느 단계가 왜 실패했는지 알려줍니다 — 이것이 바로 닥터가 존재하는 이유입니다. 왜냐하면 여기의 모든 실패 모드는 그렇지 않으면 AI 클라이언트 내부에서 "도구가 작동하지 않았습니다"라는 무용한 메시지로 나타나기 때문입니다.

그런 다음 빌드하세요:

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에 넣으세요 (macOS에서는 ~/Library/Application Support/Claude/, Windows에서는 %APPDATA%\Claude\).

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

표준 stdio MCP 서버입니다. node dist/main.js를 실행하세요; stdout에서 JSON-RPC를 사용하고 로그는 stderr로만 출력합니다.

도구

읽기

쓰기

진단

SP_MODE=read-only에서는 쓰기 도구가 광고되고 거부되는 대신 아예 광고되지 않습니다. 모델이 볼 수 있는 도구는 시도하게 되어 있습니다.

알아두면 좋은 두 가지

"오늘(Today)"은 적용하는 태그가 아닙니다. 작업이 오늘(Today)에 있는 이유는 마감일이 오늘이기 때문입니다. sp_plan_for_today가 그곳에 넣는 방법입니다; TODAY 태그의 작업 목록은 순서만 저장합니다.

기간은 분 단위입니다. Super Productivity는 밀리초를 저장합니다; 이 서버는 경계에서 변환하므로 60배 차이가 나는 일은 절대 없습니다.

구성

레거시 nextcloud_user / nextcloud_password 이름도 허용되므로 기존 .env의 이름을 바꿀 필요가 없습니다.

.env 파일을 source 대신 파싱하는 이유: 앱 비밀번호는 흔히 $로 시작하며, 셸에서 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에 대해 아무것도 모릅니다. 이것은 장식이 아닙니다 — 통합 테스트 스위트가 조건부 쓰기 재시도 로직을 포함한 전체 스택을 인메모리 저장소와 고정된 시계로 오프라인에서 2초 안에 실행할 수 있는 이유입니다.

두 가지 동기화 레이아웃, 자동 감지

Super Productivity는 두 가지 원격 레이아웃을 제공했으며, 언제든지 폴더를 마이그레이션할 수 있습니다:

• 단일 파일 — sync-data.json이 스냅샷, 아카이브, 로그를 함께 보관합니다. 기본값.

• 분할 — sync-ops.json이 커밋 지점이고, sync-state.json이 스냅샷입니다. 옵트인("정밀 동기화(Surgical sync)").

레이아웃은 매 읽기마다 감지되며, 설정되지 않습니다. 분할 레이아웃에서 스냅샷은 컴팩션 시에만 다시 쓰여지므로 최대 2000개 작업만큼 지연될 수 있습니다. 이 서버는 대기 중인 로그를 재생하여 그 차이를 메우고, 재생하지 못한 것은 보고하며, 불완전한 그림을 조용히 보여주지 않습니다.

암호화

Super Productivity에서 암호화를 활성화했다면 SP_ENCRYPTION_PASSWORD에 같은 비밀번호를 설정하세요. 파이프라인 — JSON → gzip → Argon2id 파생 AES-256-GCM — 은 업스트림과 정확히 일치하며, 이전 클라이언트가 쓴 파일의 레거시 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가 없는 서버, 실패한 백업 쓰기, 툼스톤 처리된 폴더, 손상된 원격 저장소.

테스트 픽스처는 실제 동기화 파일입니다 — 동일한 봉투, 동일한 344개 작업 로그, 동일한 스키마 버전 — 모든 제목과 메모가 합성 텍스트로 대체된 형태입니다.

엔드투엔드

npm run test:e2e는 실제 Nextcloud에 대해 실행되며, 동기화 파일의 복사본에서 시드된 별도의 샌드박스 폴더에서 실행된 후 삭제됩니다. 실제 동기화 폴더는 테스트 스위트가 절대 쓰지 않습니다. 자격 증명이 설정되지 않으면 스스로 건너뜁니다.

.env에 SP_E2E_FOLDER를 설정하세요 (기본값 super-productivity-mcp-e2e). SP_SYNC_FOLDER와 달라야 합니다. 스위트는 그 안에서 파일을 생성, 덮어쓰기, 삭제합니다.

제한 사항

나중에 발견하는 대안보다 명확히 진술합니다:

• 동기화는 즉각적이지 않습니다. 변경 사항은 동기화 파일에 즉시 반영됩니다. 데스크톱과 휴대폰은 다음 동기화 때 이를 가져옵니다.

• 보관된 작업은 읽기 전용입니다. 이 서버는 보관소를 읽지만 절대 쓰지 않습니다. 작업을 보관하는 대신 완료하세요.

• 분할 레이아웃은 추가 전용입니다. 작업 로그가 가득 차면 서버는 추가 쓰기를 거부하고 Super Productivity를 한 번 열어 컴팩션할 것을 알려줍니다. 컴팩션은 부분적으로 재생된 스냅샷을 권위 있는 것으로 게시하는 것을 의미하며, 재생에 실패한 것을 조용히 버릴 수 있습니다.

• 시간 추적이나 Pomodoro는 없습니다. 이들은 로컬의 실시간 기능이며, 여기서 쓸 만한 합리적인 것이 없습니다.

• 메모와 반복 작업은 읽기 전용이며, 쓰기가 불가능합니다.

• 하위 작업 중첩은 한 단계로, Super Productivity 자체와 일치합니다.

문제 해결

크레딧

Johannes Millan의 Super Productivity를 기반으로 구축되었습니다. 여기의 작업 로그 형식, 벡터 클록 알고리즘 및 리듀서 의미론은 해당 프로젝트 자체 구현의 포트입니다 — 이 서버가 배워야 했던 아키텍처는 docs/sync-and-op-log/를 참조하세요.

라이선스

MIT