Supatask

🚀 ⚡ Supatask

Supatask 是一個基於 Redis 的本地任務管理器，它具備現代的 Web 界面、功能豐富的命令行界面（CLI），並且集成了 MCP 服務器，為用戶提供便捷高效的任務管理體驗。

🚀 快速開始

1. 啟動應用程序

# 啟動 Docker 容器
docker compose up -d

# 驗證服務是否正在運行
curl http://localhost:8000/health

2. 訪問 Web 界面

在瀏覽器中打開 http://localhost:8000，即可使用功能齊全的 Web 用戶界面。

3. 安裝 CLI（可選）

一鍵安裝：

./install-cli.sh

手動安裝：

cd cli

4. 使用 CLI

# 列出任務
python cli/supatask_cli.py list

# 添加任務
python cli/supatask_cli.py add "Fix bug" --tags "urgent,backend"

# 開始時間跟蹤
python cli/supatask_cli.py start 1

# 停止時間跟蹤
python cli/supatask_cli.py stop 1

# 查看日誌
python cli/supatask_cli.py logs --limit 20

✨ 主要特性

• ✅ 任務管理：支持完整的 CRUD 操作，可對任務添加標籤並跟蹤狀態。
• ⏱️ 時間跟蹤：能夠啟動/停止任務的計時器，並提供歷史記錄跟蹤。
• 📊 篩選功能：可根據任務狀態、標籤和日期範圍對任務進行篩選。
• 📝 日誌記錄：提供活動和系統日誌，並支持歷史分析。
• 🌐 Web 界面：擁有現代、響應式的暗黑模式用戶界面。
• 💻 豐富的 CLI：具備美觀的命令行界面，支持表格和顏色顯示。
• 🤖 MCP 服務器：通過模型上下文協議（Model Context Protocol）集成 AI 助手。

🔧 技術細節

架構

• 後端：使用 FastAPI（Python 3.11+）構建。
• 數據庫：採用 Redis 並開啟 AOF 持久化。
• 前端：使用原生 JavaScript 和現代 CSS 技術。
• CLI：基於 Typer + Rich 實現。
• 部署：通過 Docker Compose 進行部署。

數據模型

任務以以下結構存儲在 Redis 中：

task:{id}          Hash with title, description, status, created_at, updated_at
task:{id}:tags     Set of tags
task:{id}:time     Stream of time tracking entries
tasks              Set of all task IDs
tasks:by_status:{status}  Set of task IDs by status
logs:activity      Stream of user-facing activity logs
logs:system        Stream of debug/system logs

開發

後端開發

後端在開發模式下支持熱重載：

docker-compose up

編輯 backend/ 目錄下的文件，服務器將自動重新加載。

停止應用程序

docker-compose down

若要同時移除 Redis 數據卷，可使用以下命令：

docker-compose down -v

配置

環境變量（在 docker-compose.yml 中設置）：

• REDIS_URL - Redis 連接 URL（默認值：redis://redis:6379）
• LOG_LEVEL - 日誌記錄級別（默認值：INFO）

📚 詳細文檔

CLI 命令

API 端點

任務相關

• POST /tasks - 創建任務
• GET /tasks - 列出任務（支持查詢參數：status、tags、created_after、created_before）
• GET /tasks/{id} - 獲取任務詳細信息
• PUT /tasks/{id} - 更新任務
• DELETE /tasks/{id} - 刪除任務
• POST /tasks/{id}/start - 開始計時器
• POST /tasks/{id}/stop - 停止計時器

日誌相關

• GET /logs - 獲取日誌（支持查詢參數：log_type、start_time、end_time、limit）

MCP（HTTP 可流式傳輸）

• POST /mcp/ - JSON-RPC 2.0 端點（支持 initialize、tools/list、tools/call、ping 方法）
• GET /mcp/ - 可選的服務器發起消息的 SSE 流

MCP 集成

Supatask 包含一個實現了 HTTP 可流式傳輸（MCP 規範 2025-06-18）的 MCP 服務器，用於集成 AI 助手。

可用工具

• create_task - 創建帶標籤的任務
• read_task - 讀取任務詳細信息
• list_tasks - 按條件篩選並列出任務
• update_task - 更新任務
• delete_task - 刪除任務
• get_logs - 獲取活動/系統日誌

Claude Code 配置

在 ~/.config/claude-code/mcp.json 中添加以下內容：

{
  "mcpServers": {
    "supatask": {
      "url": "http://localhost:8000/mcp/",
      "transport": "http"
    }
  }
}

協議詳情

• 規範：MCP 2025-06-18
• 傳輸方式：HTTP 可流式傳輸
• 消息格式：JSON-RPC 2.0
• 會話管理：通過 Mcp-Session-Id 頭部實現

示例用法

# 初始化連接
curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'

# 列出可用工具
curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":2}'

# 創建任務
curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"create_task","arguments":{"title":"My Task","tags":["work"]}},"id":3}'

📄 許可證

本項目採用 MIT 許可證。