Task MCP - 滴答清单 MCP 服务器

一个基于 Model Context Protocol (MCP) 的 TypeScript 项目，用于与 滴答清单 (Dida365) 进行 API 集成，允许 AI 助手（如 Claude、Gemini 等）通过 MCP 协议管理用户的滴答清单任务。

✨ 功能特性

• 🔄 完整的任务管理: 支持获取、创建、更新、删除、完成任务
• 📅 智能日期筛选: 支持今天、昨天、最近7天等多种筛选模式
• 🏷️ 项目管理: 自动匹配项目名称，支持模糊匹配
• 🕐 时区处理: 自动处理 UTC 与北京时间的转换
• ✅ 参数验证: 使用 Zod 进行严格的输入校验

📁 项目结构

task-mcp/
├── .env                    # 环境变量配置
├── .env.example            # 环境变量示例
├── package.json            # 项目配置
├── tsconfig.json           # TypeScript 配置
├── didaAPI.md              # 滴答清单 OpenAPI 完整文档
└── src/
    ├── index.ts            # 主入口：MCP 服务器 + HTTP 端点
    ├── api/
    │   └── dida.ts         # 滴答清单 API 客户端封装
    ├── tools/
    │   └── task.ts         # 任务工具实现（核心业务逻辑）
    ├── types/
    │   └── index.ts        # TypeScript 类型定义
    └── utils/
        └── date.ts         # 日期工具（UTC ↔ 北京时间转换）

🚀 快速开始

1. 安装依赖

yarn install
# 或
npm install

2. 配置环境变量

复制 .env.example 为 .env 并填写配置：

cp .env.example .env

编辑 .env 文件：

# 滴答清单 API 访问令牌
DIDA_ACCESS_TOKEN=your_access_token_here

# 服务端口（可选，默认 3000）
PORT=3010

💡 获取 Access Token: 访问 滴答清单开发者中心 注册应用并完成 OAuth 授权流程。

3. 启动服务

# 开发模式（热重载）
yarn dev

# 生产模式
yarn start

服务启动后，MCP 端点为：http://localhost:3010/mcp

🔧 MCP 工具

本项目提供以下 5 个 MCP 工具：

get_tasks - 获取任务列表

获取任务列表，支持多种筛选条件。

create_task - 创建任务

创建新任务。

update_task - 更新任务

更新现有任务的属性。

⚠️ 注意: 将 status 设置为 2 会调用完成任务接口。取消完成（status=0）不受官方 API 支持。

delete_task - 删除任务

删除指定任务。

complete_task - 完成任务

将任务标记为已完成。

🌐 技术架构

┌─────────────────┐     HTTP/MCP      ┌─────────────────┐     HTTPS     ┌─────────────────┐
│   AI 助手       │ ◄──────────────► │   Task MCP      │ ◄───────────► │  滴答清单 API   │
│ (Claude/Gemini) │                   │   (本服务)       │               │  api.dida365.com│
└─────────────────┘                   └─────────────────┘               └─────────────────┘

• 传输协议: StreamableHTTPServerTransport
• HTTP 端点: /mcp（MCP 通信）、/health（健康检查）
• API 客户端: 基于 Fetch API 封装滴答清单 OpenAPI
• 时区处理: 自动处理 UTC ↔ 北京时间 (Asia/Shanghai) 转换

📝 使用示例

在 MCP 客户端中配置

{
  "mcpServers": {
    "task-mcp": {
      "url": "http://localhost:3010/mcp"
    }
  }
}

示例对话

用户：帮我查看今天的任务

AI：调用 get_tasks 工具，参数 mode="today"

用户：创建一个任务"完成项目报告"，高优先级，截止日期是明天

AI：调用 create_task 工具，参数 title="完成项目报告", priority=5, due_date="2026-01-30"

用户：把"完成项目报告"标记为完成

AI：调用 complete_task 工具，参数 task_id="完成项目报告"

🔑 优先级对照表

📚 相关文档

• 滴答清单开发者中心
• MCP 官方文档
• 项目内置 API 文档：didaAPI.md

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License