Todo MCP

🚀 TODO MCP Server

這是一個基於模型上下文協議（MCP）的服務器，使用 Bun 和 TypeScript 構建，用於管理待辦事項列表和任務，並支持通過 Webhook 進行通知。它能夠高效地處理待辦事項的各項操作，為用戶提供便捷的任務管理體驗。

✨ 主要特性

待辦事項列表管理

• 創建：可創建帶有名稱和描述的新待辦事項列表。
• 讀取：能夠讀取單個列表或獲取所有列表。
• 更新：可更新列表的名稱和描述。
• 刪除：刪除列表時，會級聯刪除所有相關的待辦事項。

待辦事項管理

• 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

基礎用法

以下是一些基本操作的示例代碼：

創建待辦事項列表

{
  "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
}

📚 詳細文檔

MCP 工具

服務器提供了以下 MCP 工具：

待辦事項列表操作

• createTodoList - 創建新的待辦事項列表
• getTodoList - 根據 ID 獲取待辦事項列表
• getAllTodoLists - 獲取所有待辦事項列表
• updateTodoList - 更新待辦事項列表
• deleteTodoList - 刪除待辦事項列表

待辦事項操作

• createTodoItem - 創建新的待辦事項
• getTodoItem - 根據 ID 獲取待辦事項
• searchTodoItems - 搜索和過濾待辦事項
• updateTodoItem - 更新待辦事項
• markTodoDone - 將待辦事項標記為已完成
• deleteTodoItem - 刪除待辦事項

數據庫架構

服務器使用 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 分鐘檢查一次未來一小時內到期的任務。
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": {}
  }
}

API 參考

重複類型

• 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. 數據庫鎖定錯誤：確保只有一個服務器實例在運行。
2. 權限被拒絕：檢查數據庫路徑的文件權限。
3. Webhook 無法工作：驗證 Webhook URL 是否正確且可訪問。

調試模式

設置 NODE_ENV=development 以啟用額外的日誌記錄。

支持

如果遇到問題或有疑問，請按以下步驟操作：

1. 查看上述故障排除部分。
2. 在 GitHub 上搜索現有問題。
3. 創建一個包含詳細信息的新問題。