Todo MCP

🚀 TODO MCP Server

このアプリケーションは、Webhook通知を備えたTodoリストとアイテムを管理するためのModel Context Protocol (MCP)サーバーです。BunとTypeScriptを使用して構築されています。

✨ 主な機能

タスクリスト管理

• 作成：名前と説明を付けて新しいタスクリストを作成します。
• 読み取り：個々のリストを読み取るか、すべてのリストを取得します。
• 更新：リストの名前と説明を更新します。
• 削除：リストを削除します（すべてのアイテムにも影響します）。

タスクアイテム管理

• CRUD操作：タスクアイテムの作成、読み取り、更新、削除が可能です。
• 担当者サポート：タスクを特定の人物に割り当てることができます。
• 優先度レベル：なし、低、中、高
• ステータス追跡：保留中、進行中、完了、キャンセル
• タグ：カテゴリ分けのための柔軟なタグシステム
• 期限日：タスクの期限を設定できます。
• スヌーズ機能：特定の時間までアイテムを一時的に非表示にすることができます。

高度な機能

• 繰り返し：毎日、毎週、毎月、または特定の曜日
• 検索：タイトル、説明、またはキーワードでタスクを検索できます。
• フィルタリング：担当者、タグ、ステータス、優先度、期限日でフィルタリングできます。
• ソート：時間、優先度、作成日、または更新日でソートできます。
• ページネーション：大量のデータセットに対する制限とオフセット
• 通知：期限が近づいたタスクに対するWebhook通知

📦 インストール

前提条件

• Bun ランタイム
• SQLite3（ほとんどのシステムに含まれています）

セットアップ

# リポジトリをクローンする
git clone <repository-url>
cd mcp-todo

# 依存関係をインストールする
bun install

# 環境変数を設定する
cp .env.example .env
# .envを編集して設定を入力する

環境変数

# タスク通知用のWebhook URL（オプション）
NOTIFICATION_WEBHOOK=http://localhost:3000/api/webhooks/your-webhook-url

# データベース設定
DATABASE_PATH=./todo.db

# サーバー設定
MCP_SERVER_NAME=mcp-todo
MCP_SERVER_VERSION=1.0.0

💻 使用例

開発環境

# 自動再読み込み付きで開発モードで起動する
bun run dev

# 型チェックを実行する
bun run typecheck

# テストを実行する
bun test

本番環境

# サーバーを起動する
bun run start

# または、Dockerでビルドして実行する
docker-compose up -d

MCPツール

サーバーは以下のMCPツールを提供します。

タスクリスト操作

• createTodoList - 新しいタスクリストを作成する
• getTodoList - IDでタスクリストを取得する
• getAllTodoLists - すべてのタスクリストを取得する
• updateTodoList - タスクリストを更新する
• deleteTodoList - タスクリストを削除する

タスクアイテム操作

• createTodoItem - 新しいタスクアイテムを作成する
• getTodoItem - IDでタスクアイテムを取得する
• searchTodoItems - タスクアイテムを検索およびフィルタリングする
• updateTodoItem - タスクアイテムを更新する
• markTodoDone - タスクアイテムを完了としてマークする
• deleteTodoItem - タスクアイテムを削除する

基本的な使用法

// タスクリストの作成
{
  "name": "Work Tasks",
  "description": "Tasks related to work projects"
}

// タスクアイテムの作成
{
  "list_id": "list-uuid",
  "title": "Complete project documentation",
  "description": "Write comprehensive docs for the new feature",
  "assignee": "john.doe@example.com",
  "priority": "high",
  "tags": ["documentation", "urgent"],
  "due_date": "2024-12-31T23:59:59Z",
  "recurrence": {
    "type": "weekly",
    "weekdays": [1, 3, 5]
  }
}

// タスクアイテムの検索
{
  "query": "documentation",
  "status": ["pending", "in_progress"],
  "priority": ["high", "medium"],
  "assignee": "john.doe@example.com",
  "due_before": "2024-12-31T23:59:59Z",
  "sort_field": "due_date",
  "sort_order": "asc",
  "limit": 10
}

🔧 技術詳細

データベーススキーマ

サーバーはSQLiteを使用しており、以下のテーブルがあります。

• todo_lists：タスクリストの情報を格納します。
• todo_items：個々のタスクアイテムを格納します。
• tags：一意のタグ名を格納します。
• todo_tags：タスクとタグの多対多の関係を格納します。
• recurrences：タスクの繰り返しパターンを格納します。

Dockerデプロイメント

Docker Composeを使用する場合

# サービスを起動する
docker-compose up -d

# ログを表示する
docker-compose logs -f

# サービスを停止する
docker-compose down

Dockerを直接使用する場合

# イメージをビルドする
docker build -t mcp-todo .

# コンテナを実行する
docker run -d \
  --name mcp-todo \
  -v todo-data:/data \
  -e NOTIFICATION_WEBHOOK=your-webhook-url \
  mcp-todo

通知

NOTIFICATION_WEBHOOKが設定されている場合、サーバーは以下のことを行います。

1. 5分ごとに次の1時間以内に期限が切れるタスクをチェックします。
2. 期限が近づいたタスクに対してWebhook通知を送信します。
3. スパムを避けるために、通知を1時間自動的にスヌーズします。
4. タイトル、担当者、優先度、タグなどのタスク詳細を含めます。

Webhookペイロード形式

{
  "content": "Task deadline approaching!",
  "data": {
    "id": "string";
    "list_id": "string";
    "title": "string";
    "description": "string";
    "assignee": "string";
    "priority": "none"; // none, low, medium, high
    "status": "completed"; // pending, in_progress, completed, cancelled
    "tags": [];
    "due_date": Date;
    "snoozed_until": Date;
    "recurrence": {
      "type": "daily"; // daily, weekly, monthly, weekdays 
      "weekdays": []; // 0-6 for Sunday-Saturday
      "day_of_month": 1; // 1-31
      "next_due": Date;
    };
    "completed_at"?: Date;
    "created_at": Date;
    "updated_at": Date;
    "metadata": {};
  }
}

📚 ドキュメント

繰り返しタイプ

• daily：毎日繰り返します。
• weekly：特定の曜日に繰り返します（0=日曜日、6=土曜日）。
• monthly：月の特定の日に繰り返します。
• weekdays：平日（月曜日から金曜日）にのみ繰り返します。

優先度レベル

• none：優先度が設定されていません。
• low：低い優先度。
• medium：中程度の優先度。
• high：高い優先度。

ステータスオプション

• pending：タスクが開始されていません。
• in_progress：タスクが進行中です。
• completed：タスクが完了しました。
• cancelled：タスクがキャンセルされました。

開発

プロジェクト構造

src/
├── db/           # データベース接続とスキーマ
├── models/       # データアクセスのためのリポジトリクラス
├── server/       # MCPサーバーの実装
├── types/        # TypeScriptの型定義
└── utils/        # ユーティリティ関数

テスト

# すべてのテストを実行する
bun test

# カバレッジ付きで実行する
bun test --coverage

# 特定のテストファイルを実行する
bun test tests/todo-list.repository.test.ts

コントリビュート方法

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. 変更を加えます。
4. 新しい機能に対するテストを追加します。
5. すべてのテストが通過することを確認します。
6. プルリクエストを送信します。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。

トラブルシューティング

一般的な問題

1. データベースがロックされているエラー：サーバーのインスタンスが1つだけ実行されていることを確認してください。
2. アクセス権が拒否された：データベースパスのファイルアクセス権を確認してください。
3. Webhookが機能しない：Webhook URLが正しく、アクセス可能であることを確認してください。

デバッグモード

NODE_ENV=developmentを設定すると、追加のログが有効になります。

サポート

問題や質問がある場合は、以下のことを行ってください。

1. 上記のトラブルシューティングセクションを確認します。
2. GitHub上の既存の問題を検索します。
3. 詳細な情報を含めて新しい問題を作成します。