# 滴答清单 MCP 服务

这是一个为滴答清单（TickTick/Dida365）开发的 Model Context Protocol (MCP) 服务器，使用 TypeScript 编写。该服务允许 AI 助手通过标准化接口与滴答清单 API 进行交互。

## 功能特性

- ✅ 创建、读取、更新、删除任务
- ✅ 管理项目和项目列表
- ✅ 支持任务优先级和截止日期
- ✅ 通过环境变量安全配置 API Token
- ✅ 完整的 TypeScript 类型支持
- ✅ 错误处理和API响应验证

## 快速开始

### 使用MCP (Node版本)

#### DIDA官方获取token

[OpenAPI - API Doc](https://developer.dida365.com/docs/index.html#/openapi?id=get-access-token)

#### 下载

```
npm i dida365-mcp-servers
```

##### 配置json文件

```json
    "dida365": {
      "command": "node",
      "args": [
 			//your download path ; example:C:\\nvm4w\\nodejs\\node_modules\\dida365-mcp-servers\\dist
      ],
      "env": {
        "DIDA365_TOKEN": your TOKEN
      }
    }
```



### 使用本地

### 1. 安装依赖

```bash
npm install
```

### 2. 配置环境变量

复制示例环境变量文件：

```bash
cp .env.example .env
```

编辑 `.env` 文件，添加你的滴答清单 API Token：

```bash
DIDA365_TOKEN=Bearer your_token_here
```

### 3. 获取 API Token

1. 访问 [滴答清单开放平台](https://developer.dida365.com/)
2. 登录你的滴答清单账号
3. 创建新应用
4. 获取访问令牌（Access Token）
5. 将令牌添加到 `.env` 文件中

### 4. 构建和运行

开发模式：

```bash
npm run dev
```

生产模式：

```bash
npm run build
npm start
```

## 可用工具

### 任务管理

#### `create_task` - 创建新任务
- **参数**:
  - `title` (string, 必需): 任务标题
  - `projectId` (string, 必需): 项目ID
  - `content` (string): 任务内容描述
  - `dueDate` (string): 截止日期 (ISO 8601格式)
  - `priority` (number): 优先级 (0-5)

#### `get_task_by_projectId_and_taskId` - 通过项目ID和任务ID获取任务
- **参数**:
  - `projectId` (string, 必需): 项目ID
  - `taskId` (string, 必需): 任务ID

#### `get_tasks_by_projectId` - 通过项目ID获取项目中的任务列表
- **参数**:
  - `projectId` (string, 必需): 项目ID

#### `update_task` - 更新任务
- **参数**:
  - `taskId` (string, 必需): 任务ID
  - `title` (string): 任务标题
  - `content` (string): 任务内容
  - `dueDate` (string): 截止日期
  - `priority` (number): 优先级
  - `status` (number): 任务状态 (0: 未完成, 1: 已完成)

#### `delete_task` - 删除任务
- **参数**:
  - `taskId` (string, 必需): 任务ID
  - `projectId` (string, 必需): 项目ID

#### `complete_task` - 完成任务
- **参数**:
  - `taskId` (string, 必需): 任务ID
  - `projectId` (string, 必需): 项目ID

### 项目管理

#### `get_projects` - 获取项目列表
- **参数**: 无

#### `get_project_by_projectId` - 根据项目ID获取项目
- **参数**:
  - `projectId` (string, 必需): 项目ID

#### `create_project` - 创建新项目
- **参数**:
  - `name` (string, 必需): 项目名称
  - `color` (string): 项目颜色, 例如 "#F18181"
  - `sortOrder` (integer): 排序值, 默认为0
  - `viewMode` (string): 视图模式 ("list", "kanban", "timeline")
  - `kind` (string): 项目类型 ("TASK", "NOTE")

#### `update_project_by_projectID` - 根据projectId更新项目
- **参数**:
  - `projectId` (string, 必需): 项目ID
  - `name` (string): 项目名称
  - `color` (string): 项目颜色
  - `sortOrder` (integer): 排序值, 默认为0
  - `viewMode` (string): 视图模式 ("list", "kanban", "timeline")
  - `kind` (string): 项目类型 ("TASK", "NOTE")

#### `update_project_by_projectID` - 根据projectId删除项目
- **参数**:
  - `projectId` (string, 必需): 项目ID

## 可用资源

### `dida365://tasks`

获取所有任务的JSON格式概览

### `dida365://projects`

获取所有项目的JSON格式概览

## 项目结构

```
├── src/
│   └── index.ts          # 主服务器文件
├── dist/                 # 编译输出目录
├── .env.example          # 环境变量示例
├── package.json          # 项目配置
├── tsconfig.json        # TypeScript 配置
└── README.md            # 项目文档
```

## API 接口说明

本服务使用滴答清单官方 API：

- 基础URL: `https://api.dida365.com/open/v1`
- 认证方式: Bearer Token
- 请求格式: JSON
- 官方文档: https://developer.dida365.com/api#/openap

## 错误处理

服务包含完整的错误处理机制：

- API 调用失败时返回详细错误信息
- 网络错误和超时处理
- 参数验证和类型检查
- Token 验证

## 开发说明

## 贡献

欢迎提交 Issue 和 Pull Request！