Todo Mcp

日程 TypeScript

🚀 TODO MCP Server

这是一个基于Model Context Protocol (MCP) 的服务器，用于管理待办事项列表和事项，并支持通过Webhook进行通知。它使用Bun和TypeScript构建。

✨ 主要特性

待办事项列表管理

创建：可创建带有名称和描述的新待办事项列表。
读取：可查看单个列表或获取所有列表。
更新：可更新列表的名称和描述。
删除：可删除列表（会级联删除所有关联的待办事项）。

待办事项管理

CRUD操作：可创建、读取、更新和删除待办事项。
负责人支持：可将待办事项分配给特定人员。
优先级级别：无、低、中、高。
状态跟踪：待处理、进行中、已完成、已取消。
标签：灵活的标签系统，用于分类。
截止日期：可为任务设置截止日期。
暂停功能：可暂时隐藏事项，直到特定时间。

高级特性

重复周期：每日、每周、每月或特定工作日。
搜索：可按标题、描述或关键词查找待办事项。
过滤：可按负责人、标签、状态、优先级、截止日期进行过滤。
排序：可按时间、优先级、创建日期或更新日期排序。
分页：可对大型数据集进行限制和偏移。
通知：临近截止日期时，可通过Webhook发送通知。

📦 安装指南

前提条件

Bun 运行时
SQLite3（大多数系统已包含）

安装步骤

# 克隆仓库
git clone 
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上搜索现有问题。
创建一个包含详细信息的新问题。

0 条评论
分类：日程