Super Productivity MCP

AIアシスタントにタスクへの本物のアクセスを — ローカルファーストを手放さずに。

Nextcloud に置いてある同期ファイルを通じて、あなたの Super Productivity タスクを読み書きする MCP サーバーです。プラグイン不要、フォーク不要、 追従が必要な別アプリも不要です。

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

なぜこれを作ったのか

Super Productivity は意図的にローカルファーストです。リモート API も外向きの webhook もなく、デスクトップアプリのローカル REST API は 127.0.0.1 にバインド されており、設計上どこからも到達できません。CalDAV プラグインがエクスポートする のは日付が設定済みのタスクだけで、しかもカレンダーのイベントとしてであり、 タスクとしてはエクスポートされません。

同期ファイルは違います。そこにはすべてが入っています。すべてのプロジェクト、 すべてのタグ、日付のないバックログ全体、サブタスク、見積もり、時間追跡。 それはすでにあなたのサーバー上にあります。完全な全体像であり、他には何もありません。

そこで、このサーバーはそのファイルと通信します。

Related MCP server: Nextcloud MCP Server

安全性の仕組み

このアイデアの素朴な実装 — JSON をダウンロードして編集してアップロードする — は、いずれタスク履歴を破壊します。Super Productivity はタスクが入ったファイル ではなく、ベクタークロック付きの操作ログであり、あなたのデバイスはファイルを 比較するのではなく操作を再生することで変更をマージします。

このサーバーはそのプロトコルに正しく参加します。アカウント上のもう1台のデバイス として振る舞います。

具体的には、すべての書き込みは:

1. 強い ETag で読み取ります。 Nextcloud の OC-ETag は、リバースプロキシが 通常の ETag を書き換えても生き残ります。

2. Super Productivity 自身のリデューサーの忠実な移植を通じて変更を適用します。 これにより TODAY は仮想タグのままであり、dueDay と dueWithTime は 相互排他のままであり、タスクの完了が期限日を勝手に発明することはありません。

3. 対応する操作を発行します。 このサーバーのクライアント ID と増分された ベクタークロックを使って。他のデバイスがそれを競合としてフラグ付けするのでは なく、因果的に新しいものとして受け入れるように。

4. プライマリファイルに触れる前に .bak を更新します。

5. 読み取ったリビジョンに対して条件付きで書き込みます。 無条件には決して 書きません。別のデバイスが先に書き込んだ場合、ミューテーション全体が新しい 状態に対して再実行されます — 相手の変更は生き残り、あなたの変更はその上に 適用されます。

実稼働の Nextcloud に対して検証済み: If-Match は本当に強制され、 作成/スケジュール/完了/削除のフルサイクル後も、リモートはアーカイブと 未変更の状態がバイト単位で同一の、有効なスキーマ4エンベロープのままです。

クイックスタート

要件: 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

ログインパスワードではなくアプリパスワードを使用してください: 設定 → セキュリティ → デバイスとセッション → 新しいアプリパスワードを作成。 スコープ付きで、失効可能で、二要素認証が有効なときに機能する唯一の方法です。

何かに配線する前に、すべてをチェックします:

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.

ドクターは決して書き込みません。ステップが失敗した場合、どのステップがなぜ 失敗したかを示します — それがドクターを持つことのすべての意味です。なぜなら、 ここでのすべての失敗モードは、そうでなければ 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 では、書き込みツールは広告されず拒否されるのではなく、 まったくアドバタイズされません。モデルが見えるツールは、試そうとするツールです。

知っておくべき2つのこと

「今日」は適用するタグではありません。 タスクが今日にあるのは、期限日が 今日だからです。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 は2つのリモートレイアウトを出荷しており、いつでもフォルダを 移行できます:

• 単一ファイル — sync-data.json がスナップショット、アーカイブ、ログを まとめて保持します。デフォルト。

• 分割 — sync-ops.json がコミットポイント、sync-state.json が スナップショット。オプトイン(「サージカル同期」)。

レイアウトは読み取りのたびに検出され、設定されることはありません。分割レイアウトでは スナップショットはコンパクション時のみ書き換えられるため、最大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を一度開いてコンパクションできるようにするよう指示します。コンパクションは、部分的に再生されたスナップショットを権威あるものとして公開することを意味し、再生に失敗したものを静かに破棄する可能性があります。

• 時間追跡やポモドーロはありません。 これらはローカルのライブ機能であり、ここから書き込むべき意味のあるものはありません。

• ノートと繰り返しタスクは読み取り専用で、書き込みはできません。

• サブタスクのネストは1レベルまでで、Super Productivity自体と一致しています。

トラブルシューティング

クレジット

Johannes MillanによるSuper Productivityを基に構築されています。ここでの操作ログ形式、ベクタークロックアルゴリズム、リデューサーセマンティクスは、そのプロジェクト自身の実装の移植です。このサーバーが学ばなければならなかったアーキテクチャについては、docs/sync-and-op-log/を参照してください。

ライセンス

MIT