todo-list-mcp

一个基于 Model Context Protocol (MCP) 的待办事项列表服务器，允许 AI 模型（如 Claude）与您的待办事项进行交互。支持标准 CalDAV 协议，可与 Nextcloud 等服务无缝集成。

功能特性

• 完整 CRUD：创建、查询、更新、完成、删除待办事项。
• 时间管理：支持开始时间、截止时间、多重提醒。
• 分类与优先级：支持标签（Tags）和优先级（Low/Medium/High）。
• 增强搜索：
  • 支持按标题部分匹配。
  • 支持按日期、日期范围、相对偏移量（如 now, +1d, -2h）进行精确到秒的搜索。
• 范围限制：所有列表和搜索工具均支持 limitStart 和 limitEnd 参数，默认为当前时间前后 6 个月，确保性能。
• 时区支持：通过 TZ 环境变量自定义交互时区。

支持的 CalDAV 扩展

| 功能 | 字段名 | 类型 | 描述 | |------|--------|------|------| | 开始时间 | startDate | string (ISO 8601) | 任务开始的时间 | | 截止时间 | dueDate | string (ISO 8601) | 任务截止的时间 | | 优先级 | priority | enum | 'low', 'medium', 'high' | | 提醒 | reminders | string[] | 多个提醒时间（ISO 8601） | | 标签 | tags | string[] | 任务分类标签 |

安装

使用 npx（推荐）

npx todo-list-mcp

从源码安装

git clone <repository-url>
cd todo-list-mcp
npm install
npm run build
npm start

配置

此服务器需要 CalDAV 账户信息才能运行。您需要设置以下环境变量：

# CalDAV 服务地址
NEXTCLOUD_URL=https://your-nextcloud-instance.com/remote.php/dav
# 用户名
NEXTCLOUD_USERNAME=your-username
# 密码或应用密码
NEXTCLOUD_PASSWORD=your-app-password
# 时区（可选，默认为 Asia/Shanghai）
TZ=Asia/Shanghai

或者创建一个 .env 文件（参考 .env.example）。

API 工具

create-todo

创建新的待办事项。如果未指定开始和截止时间，默认设为当天全天事件。

list-todos

列出所有待办事项。支持 limitStart / limitEnd 过滤。

get-todo-byID

通过 UUID 获取特定待办事项详情。

update-todo-byID

更新现有待办事项的任何属性。

complete-todo-byID

将待办事项标记为已完成。

delete-todo-byID

从服务器永久删除待办事项。

search-todos-by-title

按标题搜索。支持 limitStart / limitEnd 过滤。

search-todos-by-date

按日期搜索。支持：

• date: 基准时间 (now, 2025-12-18, ISO 8601)。
• endDate: 结束时间，用于范围搜索。
• offset: 相对偏移量 (如 1d, -2h, 30m)。

list-active-todos

列出所有未完成的待办事项。

summarize-active-todos

生成活动待办事项的 Markdown 摘要。

开发与测试

编译

npm run build

部署测试工具

运行集成测试以验证您的服务器配置和所有工具链：

npm run deploy-test

该工具会模拟完整的业务流程并生成 deploy-test-report.md。

项目结构

src/
├── models/
│   └── Todo.ts              # 数据模型与 Zod 模式
├── services/
│   └── TodoService.ts       # 核心业务逻辑与 CalDAV 交互
├── utils/
│   └── formatters.ts        # 时区感知的格式化工具
├── index.ts                 # MCP 服务器入口
└── deploy-test.ts           # 集成测试客户端

许可证

ISC License