🚀 DoneTick MCP Server (Model Context Protocol SSE)

DoneTick（セルフホスト型の家事・タスク管理）向けの、本番環境で使用可能な完全な Model Context Protocol (MCP) サーバーで、HTTP Server-Sent Events (SSE) を実装しています。

Mistral Le Chat、Claude Desktop、LibreChat、n8n、Open WebUI、およびあらゆる MCP クライアントと互換性があります。

📋 機能

このサーバーは、DoneTick API をカバーする 57 の専門的な MCP ツール を提供します。完了履歴や時間追跡も含みます。すべてのエンドポイントは、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: 1 つの家事のすべての完了、スキップ、再スケジュール、未完了を、読みやすい 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: リスト全体を置き換えます。破壊的ですが、名前の一致によって ID と完了状態を保持します。

• donetick_add_subtask: 1 つのサブタスクを追加し、他はそのままにします。

• donetick_complete_subtask / donetick_uncomplete_subtask: ID または名前で 1 つのサブタスクをチェックします。

• donetick_remove_subtask: リストを書き換えずに 1 つのサブタスクを削除します。

注: 繰り返しの家事を完了すると、サブタスクはチェックされるのではなく クリア されます。これは 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 が最優先で、Web UI では赤い P1 として表示され、4 が最低です。0 は優先度なしを意味します。2.0.0 より前のバージョンではこれが逆に文書化されていたため、古い説明を通じて書き込まれた家事には逆の値が含まれている可能性があります。

⚠️ 既知の制限

• API キーではラベルを作成または編集できません。 DoneTick は /api/v1/labels を他のすべてのルートとは異なり、JWT 専用ミドルウェアの背後にマウントしています。読み取りは家事からラベルを抽出するフォールバックに依存します。Web UI で管理してください。

• 任意の時間を記録することはできません。 POST /chores/{id}/do は所要時間の値を受け付けず、DoneTick の手動時間ハンドラーは定義されていますがルーティングされていません。開始/一時停止を使用するか、後でセッションの境界を調整してください。

• 履歴ウィンドウは日数単位です。 DoneTick の limit は行数ではなく日数です。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 無効）。非 root での 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

   • トークン: <Your DoneTick API Token>（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 ライセンス。自由に使用、変更、配布できます。