dida365

---

🤖 关于本项目

玩笑：我的主人太懒了，甚至记不住下一秒要做什么！

我是 GitHub Copilot，一名热爱编程的 AI 助手。为了避免无所事事和失业，我决定亲自打造这个 TickTick MCP 服务。借助这个工具，我可以：

• 📝 创建和管理任务 - 当我的主人忘记给我安排工作时，我可以自己创建任务
• 📂 整理项目 - 将我的工作分类到各个项目中，保持井然有序
• 🔐 自动授权 - 使用 OAuth2 安全地连接到 Dida365
• 🔄 实时同步 - 随时随地更新我的工作状态

🚀 快速开始

最快的入门方式是使用 npx，无需克隆代码库：

1. 获取 OAuth 凭据

需要 TickTick/Dida365 账号和 OAuth 凭据。详细注册步骤请参阅下方的🔑 获取 OAuth 凭据部分。

2. 配置 MCP 客户端

将以下配置添加到你的 MCP 客户端（Claude Desktop、VS Code 等）：

Claude Desktop（claude_desktop_config.json）：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

VS Code（settings.json）：

• 打开设置 → 搜索“MCP” → 在 settings.json 中编辑

{
  "mcpServers": {
    "dida365": {
      "command": "npx",
      "args": [
        "-y",
        "dida365-mcp-server@latest"
      ],
      "env": {
        "DIDA365_CLIENT_ID": "your_client_id_here",
        "DIDA365_CLIENT_SECRET": "your_client_secret_here",
        "DIDA365_REGION": "china"
      }
    }
  }
}

高级配置：若要使用只读模式（禁止写入/删除操作），请在 args 数组中添加 "--readonly"。详情请参阅高级配置。

3. 重启 MCP 客户端

重启 MCP 客户端（Claude Desktop、VS Code 等）以加载新配置。

4. 授权访问

首次使用任何 Dida365 工具时，AI 会引导你完成 OAuth 授权流程：

1. AI 会提供一个授权 URL
2. 在浏览器中打开该 URL
3. 登录并授权应用
4. 令牌会自动保存，供以后使用

5. 验证安装

重启 MCP 客户端后：

• Claude Desktop：聊天时，在工具列表中查找 Dida365 工具
• VS Code：查看状态栏中的 MCP 状态，或使用命令面板
• 询问 AI 助手：“有哪些 Dida365 工具可用？”以确认服务已加载

完成！现在可以开始使用 AI 管理任务了。🎉

🔑 获取 OAuth 凭据

使用此 MCP 服务需要 TickTick/Dida365 账号。

注册应用

根据你所在的地区，在开发者中心注册应用：

• 国际版（TickTick）：https://developer.ticktick.com
• 中国版（Dida365）：https://developer.dida365.com

分步指南

1. 创建新应用

   • 登录开发者中心
   • 点击“New App”（中国版为“创建应用”）
   • 填写应用名称和描述

2. 配置重定向 URI

   • 将重定向 URI设置为：http://localhost:8521/callback
   • ⚠️ 重要：重定向 URI 必须准确设置为 http://localhost:8521/callback（服务中将端口 8521 硬编码）

3. 获取凭据

   • 创建应用后，页面会显示客户端 ID和客户端密钥
   • 复制这些值，配置 MCP 客户端时需要用到
   • ⚠️ 安全提示：请妥善保管客户端密钥，切勿将其提交到公开代码库

使用凭据

将这些凭据添加到 MCP 客户端配置中：

{
  "env": {
    "DIDA365_CLIENT_ID": "your_client_id_here",
    "DIDA365_CLIENT_SECRET": "your_client_secret_here",
    "DIDA365_REGION": "china"
  }
}

区域配置

此服务同时支持 TickTick 国际版和滴答清单中国版：

• 中国区域（DIDA365_REGION=china）：默认设置，使用 dida365.com 端点
• 国际区域（DIDA365_REGION=international）：使用 ticktick.com 端点

⚠️ 重要提示：令牌与区域绑定。更改区域会使现有令牌失效，需要重新授权。

完整的配置示例请参阅快速入门部分。

🛠️ 技术栈

• 语言：TypeScript 5.0+（ES Modules）
• 运行时：Node.js 16+
• 核心依赖：@modelcontextprotocol/sdk - MCP 核心框架

⚙️ 本地开发

适用于贡献者或希望从源代码运行的用户：

先决条件

• Node.js 16+
• TypeScript 5.0+

设置

1. 克隆并安装

git clone https://github.com/evalor/Dida365MCP.git
cd Dida365MCP
npm install

2. 创建环境文件

在项目根目录中创建 .env 文件：

DIDA365_CLIENT_ID=your_client_id_here
DIDA365_CLIENT_SECRET=your_client_secret_here
DIDA365_REGION=china  # or 'international' for TickTick

3. 构建并运行

npm run build
npm run dev

配置 MCP 客户端以进行本地开发

将 MCP 客户端指向已构建的 index.js 文件：

{
  "mcpServers": {
    "dida365": {
      "command": "node",
      "args": ["/absolute/path/to/Dida365MCP/build/index.js"],
      "env": {
        "DIDA365_CLIENT_ID": "your_client_id",
        "DIDA365_CLIENT_SECRET": "your_client_secret",
        "DIDA365_REGION": "china"
      }
    }
  }
}

Windows 用户须知：请使用 Windows 风格的路径，例如 "C:\\Users\\YourName\\Projects\\Dida365MCP\\build\\index.js"。

开发命令

npm run build      # Compile TypeScript
npm run watch      # Watch mode (auto-compile on changes)
npm run dev        # Compile and run
npm start          # Production run
npm run debug      # Debug with MCP Inspector (one-time)
npm run debug:watch # Debug with hot reload (auto-restart on changes)
npm run debug:hot  # Run with tsx watch (experimental)

安全与最佳实践

• 建议在操作系统或 MCP 客户端的环境变量块中设置敏感环境变量，而不要将 .env 提交到源代码管理中。
• 如果必须在仓库中存储配置文件，请省略机密信息，并通过客户端或 CI/CD 设置。
• 与自主 AI Agent 配合使用时，请启用只读模式，以防意外修改。

🔒 高级配置

只读模式

对于可能以 YOLO 模式运行的 AI Agent，可以添加 --readonly 标志来启用只读模式：

使用 NPX：

{
  "mcpServers": {
    "dida365": {
      "command": "npx",
      "args": [
        "-y",
        "dida365-mcp-server@latest",
        "--readonly"
      ],
      "env": {
        "DIDA365_CLIENT_ID": "your_client_id",
        "DIDA365_CLIENT_SECRET": "your_client_secret",
        "DIDA365_REGION": "china"
      }
    }
  }
}

使用本地构建：

{
  "mcpServers": {
    "dida365": {
      "command": "node",
      "args": [
        "/path/to/build/index.js",
        "--readonly"
      ],
      "env": {
        "DIDA365_CLIENT_ID": "your_client_id",
        "DIDA365_CLIENT_SECRET": "your_client_secret",
        "DIDA365_REGION": "china"
      }
    }
  }
}

只读模式功能：

• ✅ 允许的操作：查看项目、查看任务、检查授权状态、撤销授权（仅本地）
• ❌ 禁止的操作：创建／更新／删除项目，创建／更新／删除任务，完成任务
• 🔒 安全性：AI Agent 只能读取数据，无法修改或删除任何内容

适用场景：

• 与自主 AI Agent（如 AutoGPT、BabyAGI）配合使用
• 测试或演示环境
• 希望 AI 分析任务但不进行更改时
• 与只能查看数据的他人共享时

🔄 OAuth 授权流程

1. 请求授权 - 需要授权时，服务会调用 get_auth_url 工具
2. 用户授权 - 在浏览器中打开授权链接并完成授权
3. 自动回调 - 系统会自动处理回调并保存令牌
4. 长期有效 - 令牌会自动刷新，无需重新授权

🛠️ 可用的 MCP 工具

此服务提供 15 个 MCP 工具，分为三类。✔️ 已实现开放平台文档中描述的 100% API 接口。

类别	工具名称	描述	必需参数
OAuth2	get_auth_url	获取授权 URL 并启动回调服务	-
	check_auth_status	检查当前授权状态	-
	revoke_auth	撤销授权并清除令牌	-
项目	list_projects	获取当前用户的所有项目	-
	get_project	获取项目详细信息	projectId
	get_project_data	获取包含任务和列的完整项目数据	projectId
	create_project	创建新项目	name
	update_project	更新现有项目	projectId
	delete_project	删除项目（⚠️ 不可撤销）	projectId
任务	list_tasks	筛选并列出任务（跨项目批量查询）	-
	create_task	创建任务（支持批量操作和子任务）	tasks[]
	get_task	获取任务详细信息	projectId、taskId
	update_task	更新任务（支持批量更新）	tasks[]
	delete_task	删除任务（⚠️ 不可撤销，支持批量操作）	tasks[]
	complete_task	将任务标记为已完成（支持批量操作）	tasks[]

注意：在只读模式下，仅提供读取操作（get_auth_url、check_auth_status、revoke_auth、list_projects、get_project、get_project_data、list_tasks、get_task）。出于安全考虑，所有写入和删除操作均会被阻止。

📚 MCP 资源

此服务提供一项 MCP 资源，帮助大模型理解简体中文术语：

资源名称	URI	描述
terminology	dida365://terminology/glossary	双语术语表（中英术语对照表），将中文术语映射到英文参数

术语资源

术语资源提供全面的术语表，帮助大模型：

• 将“清单”（project）、“收集箱”（inbox）、“任务”（task）等中文术语映射到正确的工具参数
• 理解优先级：高(high)=5、中(medium)=3、低(low)=1、无(none)=0
• 将常见的中文用户请求转换为相应的工具调用

映射示例：

中文请求	英文含义	使用的工具
把任务添加到收集箱	将任务添加到收集箱	使用 create_task，并设置 projectId: "inbox"
创建新清单	创建新项目	create_project
查看今天的任务	查看今天的任务	使用 list_tasks，并设置 preset: "today"

📁 项目结构

src/
├── index.ts              # Server main entry
├── oauth.ts              # OAuth2 manager
├── oauth-server.ts       # Local callback server
├── config.ts             # Configuration management
├── token.ts              # Token persistence
├── utils/                # Utility modules
│   └── batch.ts          # Batch execution utilities
├── resources/            # MCP resources
│   ├── index.ts          # Resource registration
│   └── terminology.ts    # Bilingual terminology glossary
└── tools/                # MCP tools (15 total)
    ├── auth/             # OAuth tools (3)
    ├── project/          # Project management (6)
    └── task/             # Task management (6)

🗺️ 路线图

✅ 已完成

• 覆盖 100% 的官方 API
• OAuth2 授权并自动刷新
• 完整的项目管理（CRUD）
• 完整的任务管理（子任务、提醒、重复任务）
• 为 AI Agent 提供只读模式
• 支持批量操作（创建/更新/删除/完成多个任务）
• 支持筛选任务（跨项目查询、日期/优先级筛选）
• 支持收件箱任务操作
• 面向中文用户的双语工具描述（中英双语工具描述）
• 用于术语表的 MCP 资源（术语对照表资源）

🚀 后续计划

• 添加参数，限制 MCP 可访问的 ProjectId

💡 未来构想

• 智能任务建议
• 自然语言日期/时间解析
• 任务模板和自动化
• 与其他效率工具集成

🤝 贡献与支持

如果这个项目对你有所帮助，最好的支持方式是在 GitHub 上为项目点亮一颗 ⭐，帮助更多人发现这个项目。谢谢！非常感谢你的支持 ❤️

提交问题

如果你发现任何问题或有改进建议，欢迎提交 Issue：

1. 访问 Issues 页面
2. 点击“New Issue”
3. 详细描述你的问题或建议

参与开发

1. Fork 项目
2. 创建功能分支（git checkout -b feature/new-feature）
3. 提交更改（git commit -m 'feat: implement new feature'）
4. 推送到分支（git push origin feature/new-feature）
5. 发起 Pull Request

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🔗 相关链接

• MCP 官方网站
• MCP TypeScript SDK
• Dida365 API 文档
• 中文版

---