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. 创建一个包含详细信息的新问题。