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 许可证。