金大哥 - todo-mcp MCP 详情

article

README

🚀 TODO MCP Server

这是一个基于Model Context Protocol (MCP) 的服务器，用于管理待办事项列表和事项，并支持通过Webhook进行通知。它使用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

高级用法

创建待办事项列表

{
  "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时，服务器将：

每5分钟检查下一小时内即将到期的任务。
为即将到来的截止日期发送Webhook通知。
自动将通知暂停1小时，以避免垃圾信息。
包含任务详细信息，如标题、负责人、优先级和标签。

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

贡献代码

分叉仓库
创建功能分支
进行更改
为新功能添加测试
确保所有测试通过
提交拉取请求

📄 许可证

本项目采用MIT许可证。

故障排除

常见问题

数据库锁定错误：确保只有一个服务器实例在运行。
权限被拒绝：检查数据库路径的文件权限。
Webhook无法工作：验证Webhook URL是否正确且可访问。

调试模式

设置NODE_ENV=development以启用额外的日志记录。

支持

如有问题和疑问，请：

查看上述故障排除部分。
在GitHub上搜索现有问题。
创建一个包含详细信息的新问题。