🚀 DoneTick MCP Server (Model Context Protocol SSE)

一个完整、生产就绪的 Model Context Protocol (MCP) 服务器，为 DoneTick（自托管的家务与任务管理）实现 HTTP Server-Sent Events (SSE)。

兼容 Mistral Le Chat、Claude Desktop、LibreChat、n8n、Open WebUI 以及任何 MCP 客户端。

📋 功能特性

该服务器提供 57 个专用 MCP 工具，覆盖 DoneTick API，包括完成历史与时间跟踪。每个端点都通过 npm run smoke 针对真实实例进行验证。

1. 📝 家务与任务（donetick_*）

• donetick_list_chores：使用筛选条件（搜索、项目、状态）列出任务。

• donetick_get_chore：完整任务详情——重复规则、指派对象、子任务、标签、触发器——以及 lastCompletedDate、lastCompletedBy 和 timeSpentSeconds。

• donetick_create_chore：创建家务，支持截止日期、重复规则、优先级、积分、项目、子任务、标签、通知、审批和传感器触发器。

• donetick_update_chore：部分或完整更新。如果无法先读取家务，则中止而不是盲目写入。

• donetick_complete_chore：完成家务并安排下一次重复。

• donetick_undo_chore：撤销最后一次完成。

• donetick_delete_chore：永久删除家务（建议归档）。

• donetick_set_due_date：设置、更改或清除截止日期。

• donetick_set_priority：设置优先级——1 为最高（P1），4 为最低，0 为无。

• donetick_skip_chore：跳过当前重复。

• donetick_nudge_chore：向指派对象发送提醒通知。

• donetick_set_chore_notifications：配置提醒（截止日期、提前提醒、催促、完成）。

• donetick_set_chore_project、donetick_set_chore_assignee：重新指派家务。

2. 📊 完成历史（donetick_*）

• donetick_get_chore_history：单个家务的每次完成、跳过、重新安排和遗漏，带有可读的 statusName 和摘要。这是区分"已完成"与"已编辑"的唯一可靠方式——updatedAt 将两者混为一谈。

• donetick_get_history：圈子范围内的活动，可按日期范围和状态筛选。

• donetick_modify_history_entry：更正完成记录的记录时间或其备注。

• donetick_delete_history_entry：删除错误的记录。

3. ⏱️ 时间跟踪（donetick_*）

• donetick_start_chore / donetick_pause_chore：运行每个家务的计时器。

• donetick_get_chore_timer：总耗时以及每次工作会话。

• donetick_reset_chore_timer：清除累计时间。

• donetick_adjust_time_session / donetick_delete_time_session：事后更正历史记录。

4. 🧩 子任务（donetick_*）

• donetick_set_subtasks：替换整个列表。具有破坏性，但通过名称匹配保留 id 和完成状态。

• donetick_add_subtask：追加一个子任务，其余保持不变。

• donetick_complete_subtask / donetick_uncomplete_subtask：按 id 或名称勾选一个子任务。

• donetick_remove_subtask：删除一个子任务而不重写列表。

注意： 完成重复家务会清除其子任务，而不是勾选它们。这是 DoneTick 自身的行为，为下一次出现做好准备。

5. 🗄️ 归档与审批（donetick_*）

• donetick_list_archived_chores、donetick_archive_chore、donetick_unarchive_chore：删除的可逆替代方案。

• donetick_approve_chore、donetick_reject_chore：审核需要 requireApproval 的家务的完成情况。

6. 🏷️ 标签与标记（donetick_*）

• donetick_list_labels：列出标签，失败时回退到从家务中提取。

• donetick_create_label、donetick_update_label、donetick_delete_label：请参阅下面的限制——这些需要 JWT。

• donetick_set_chore_labels、donetick_add_chore_label：将标签附加到家务。

7. ⚡ 智能设备与事件触发器（donetick_*）

• donetick_list_things、donetick_create_thing、donetick_update_thing、donetick_delete_thing。

• donetick_set_thing_state：更新传感器或计数器，自动触发关联任务。

• donetick_get_thing_history：设备曾经保持的每个状态及其时间。

• donetick_link_thing_chore / donetick_unlink_thing_chore：触发条件（eq、neq、gt、lt、gte、lte）。

8. 📁 项目（donetick_*）

• donetick_list_projects、donetick_create_project、donetick_update_project、donetick_delete_project。

9. 👥 圈子、成员与筛选器（donetick_*）

• donetick_get_circle_info、donetick_list_members、donetick_list_filters。

Related MCP server: Deferno MCP Server

📅 日期与优先级

日期。 DoneTick 将每个日期绑定到 Go 的 time.Time，因此它只接受 RFC3339。连接器还接受 YYYY-MM-DD 和 YYYY-MM-DD HH:mm，在 DONETICK_TIMEZONE（默认 UTC）中按 DONETICK_DEFAULT_DUE_TIME（默认 18:00）解析。如果你希望"明天到期"表示合理的本地时间而不是 UTC 午夜，请同时设置两者。

优先级。 DoneTick 是倒序计数的：1 是最高优先级，在 Web UI 中显示为红色 P1，4 是最低的；0 表示无优先级。2.0.0 之前的版本将此记录反了，因此通过旧描述写入的家务可能带有颠倒的值。

⚠️ 已知限制

• 标签无法使用 API 密钥创建或编辑。 DoneTick 将 /api/v1/labels 挂载在仅限 JWT 的中间件后面，与其他所有路由不同。读取会回退到从家务中提取标签；请在 Web UI 中管理它们。

• 无法记录任意时长。 POST /chores/{id}/do 不接受耗时值，而且 DoneTick 的手动时长处理器已定义但从未路由。请使用开始/暂停，或事后调整会话的边界。

• 历史窗口以天为单位。 DoneTick 的 limit 是天数，而不是行数；since/until 在获取后在客户端应用。

🔒 安全与 OWASP 加固

• OWASP A01 与 A07（访问控制与计时攻击）：恒定时间认证令牌验证（crypto.timingSafeEqual）。

• OWASP A02（加密失败与信息泄露）：日志中的密钥脱敏，以及不带凭据的安全 /health 遥测。

• OWASP A03（注入与 SSRF）：严格的协议净化（http:、https:），防止协议注入或 SSRF（file://、gopher://）。

• OWASP A04（拒绝服务）：严格的 JSON 请求体大小限制（1mb）以及带连接清理的活跃 SSE 会话上限。

• OWASP A05（安全配置错误）：加固的 HTTP 头（X-Content-Type-Options: nosniff、X-Frame-Options: DENY、X-XSS-Protection: 0、Referrer-Policy: no-referrer、X-Powered-By 已禁用）。非 root Docker 执行（USER node）。

🐳 使用 Docker 快速开始

1. 创建 docker-compose.yml

services:
  mcp-donetick:
    image: ghcr.io/bibiwan/mcp_donetick:latest
    container_name: mcp-donetick
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - PORT=3000
      - HOST=0.0.0.0
      - DONETICK_URL=http://donetick:2021
      - DONETICK_TOKEN=
      # Resolves date-only inputs such as "2026-08-30" to a local hour
      - DONETICK_TIMEZONE=Europe/Paris
      - DONETICK_DEFAULT_DUE_TIME=18:00
      - MCP_AUTH_TOKEN=
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/health"]
      interval: 30s
      timeout: 5s
      retries: 3

2. 启动容器

docker compose up -d

🤖 连接 Mistral Le Chat

1. 在 Mistral Le Chat 中，转到 设置 ➔ 工具与 MCP（或 连接器）。

2. 点击 "添加 MCP 服务器"。

3. 填写连接设置：

   • 名称：DoneTick

   • URL：https://<your-server-host>:3000/sse

   • 认证：Bearer Token

   • 令牌：<您的 DoneTick API Token>（在 DoneTick ➔ 设置 ➔ API Token 中生成）

4. 保存并开始聊天！

示例提示词：

• "哪些家务已逾期或今天到期？"

• "创建一个家务'清洁意式浓缩咖啡机'，下周日到期，高优先级，子任务：'反冲洗冲煮头'、'除垢锅炉'。"

• "将家务 #21 链接到我的咖啡计数器（设备 #11），当计数器 >= 100 时触发。"

• "将任务 #5 标记为已完成，20 积分。"

🧪 开发与测试

# Install dependencies
npm install

# Run the test suite with coverage.
# Enforces an 80% floor on statements, branches, functions and lines.
npm test

# Build TypeScript
npm run build

# Start local server
npm start

实时冒烟测试

单元测试套件模拟了 axios，因此它证明载荷按预期成形——而不是 DoneTick 会接受它们。在标记发布之前，请针对真实实例运行冒烟测试：

DONETICK_URL=https://donetick.example DONETICK_TOKEN=xxx npm run smoke

它只创建以 [mcp-test] 为前缀的对象，测试连接器使用的每个端点，删除它创建的内容，并拒绝删除任何缺少该前缀的内容。现有家务永远不会被修改。

📄 许可证

MIT 许可证。可自由使用、修改和分发。