# TickTick MCP Server (TypeScript)

Cервер [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) для интеграции с TickTick API, написанный на TypeScript.

> 🚀 **Кстати!** Если вы работаете с ИИ и автоматизацией — обратите внимание на [**polza.ai**](https://polza.ai) — российский агрегатор API нейросетей. Никаких VPN, оплата российской картой, интеграция с n8n/Make/Zapier. Идеально для ваших AI-проектов! 🇷🇺

## Возможности

- 🔑 **Простая авторизация** - используйте access token из переменных окружения
- 📋 **Управление проектами** - создание, просмотр и удаление проектов (включая поддержку типов TASK и NOTE)
- ✅ **Управление задачами** - создание, обновление, завершение и удаление задач
- 🛠️ **Отдельный скрипт для получения токена** - простой способ получить access token
- 📊 **Информация о конфигурации** - просмотр текущих настроек через ресурсы
- 🔌 **Бесшовная интеграция с Claude** и другими MCP клиентами
- 🐳 **Docker поддержка** - запуск в контейнере с HTTP доступом
- ✅ **Надежная валидация** - автоматическая проверка и преобразование данных
- 🔄 **Retry логика** - автоматические повторы при временных ошибках
- 📝 **Детальное логирование** - подробные логи для отладки

## Предварительные требования

- Node.js 18 или выше
- npm или yarn
- TickTick API credentials (Client ID, Client Secret)

## Установка

1. **Клонируйте репозиторий**:
```bash
git clone https://github.com/polza-ai/ticktick-mcp-ts.git
cd ticktick-mcp-ts
```

2. **Установите зависимости**:
```bash
npm install
```

3. **Соберите проект**:
```bash
npm run build
```

## Аутентификация с TickTick

Этот сервер использует OAuth2 для аутентификации с TickTick. Процесс настройки простой:

### Шаг 1: Регистрация приложения

1. Зарегистрируйте ваше приложение в [TickTick Developer Center](https://developer.ticktick.com/manage)
   - Установите redirect URI как `http://localhost:8080/callback`
   - Запишите ваш Client ID и Client Secret

### Шаг 2: Настройка переменных окружения

2. Создайте файл `.env` на основе `.env.example`:

```env
# TickTick API credentials (ТОЛЬКО для получения access token)
# Получите их на https://developer.ticktick.com/manage
TICKTICK_CLIENT_ID=your_client_id_here
TICKTICK_CLIENT_SECRET=your_client_secret_here

# TickTick Access Token (ОБЯЗАТЕЛЬНО для работы)
# Получите его запустив 'npm run get-token'
TICKTICK_ACCESS_TOKEN=your_access_token_here

# TickTick API endpoints (значения по умолчанию)
TICKTICK_BASE_URL=https://api.ticktick.com/open/v1
TICKTICK_AUTH_URL=https://ticktick.com/oauth/authorize
TICKTICK_TOKEN_URL=https://ticktick.com/oauth/token

# Для Dida365 (китайская версия), раскомментируйте и используйте вместо:
# TICKTICK_BASE_URL=https://api.dida365.com/open/v1
# TICKTICK_AUTH_URL=https://dida365.com/oauth/authorize
# TICKTICK_TOKEN_URL=https://dida365.com/oauth/token
```

### Шаг 3: Получение токена доступа

3. Запустите процесс аутентификации:
```bash
npm run get-token
```

Это:
- Запустит локальный сервер на порту 8080
- Откроет окно браузера для входа в TickTick
- Автоматически сохранит ваши токены доступа в файл `.env`

### Шаг 4: Тестирование конфигурации

4. Протестируйте вашу конфигурацию:
```bash
npm test
```

Это проверит, что ваши учетные данные TickTick работают корректно и покажет реальные данные из вашего аккаунта.

## Аутентификация с Dida365

[滴答清单 - Dida365](https://dida365.com/home) - это китайская версия TickTick, и процесс аутентификации аналогичен TickTick:

1. Зарегистрируйте ваше приложение в [Dida365 Developer Center](https://developer.dida365.com/manage)
   - Установите redirect URI как `http://localhost:8080/callback`
   - Запишите ваш Client ID и Client Secret

2. Добавьте переменные окружения в ваш файл `.env`:
   ```env
   TICKTICK_BASE_URL=https://api.dida365.com/open/v1
   TICKTICK_AUTH_URL=https://dida365.com/oauth/authorize
   TICKTICK_TOKEN_URL=https://dida365.com/oauth/token
   ```

3. Следуйте тем же шагам аутентификации, что и для TickTick

## Использование

### Локальный запуск

#### С Claude for Desktop

1. Установите [Claude for Desktop](https://claude.ai/download)

2. Отредактируйте файл конфигурации Claude for Desktop:

   **macOS**:
   ```bash
   nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
   ```

   **Windows**:
   ```bash
   notepad %APPDATA%\Claude\claude_desktop_config.json
   ```

3. Добавьте конфигурацию TickTick MCP сервера, используя абсолютные пути:
   ```json
   {
      "mcpServers": {
         "ticktick": {
            "command": "node",
            "args": ["/absolute/path/to/ticktick-mcp-ts/dist/index.js"],
            "env": {
              "TICKTICK_ACCESS_TOKEN": "your_access_token_here",
              "TICKTICK_BASE_URL": "https://api.ticktick.com/open/v1"
            }
         }
      }
   }
   ```

4. Перезапустите Claude for Desktop

После подключения вы увидите инструменты TickTick MCP сервера доступными в Claude, обозначенные иконкой 🔨 (tools).

### 🐳 Запуск в Docker контейнере

Проект поддерживает запуск в Docker контейнере с использованием [supergateway](https://github.com/modelcontextprotocol/servers/tree/main/src/supergateway) для HTTP доступа к MCP серверу.

#### Быстрый старт с Docker

1. **Убедитесь, что у вас есть `.env` файл** с необходимыми переменными:
   ```env
   TICKTICK_ACCESS_TOKEN=your_access_token_here
   TICKTICK_BASE_URL=https://api.ticktick.com/open/v1
   SUPERGATEWAY_PORT=8002
   ```

2. **Запустите контейнер с помощью Docker Compose**:
   ```bash
   docker-compose up -d
   ```

3. **Или соберите и запустите вручную**:
   ```bash
   # Сборка образа
   docker build -t ticktick-mcp .
   
   # Запуск контейнера
   docker run -d \
     --name ticktick-mcp \
     -p 8002:8002 \
     -e TICKTICK_ACCESS_TOKEN=your_access_token_here \
     -e TICKTICK_BASE_URL=https://api.ticktick.com/open/v1 \
     -e SUPERGATEWAY_PORT=8002 \
     ticktick-mcp
   ```

#### Использование с Claude через HTTP

После запуска контейнера, MCP сервер будет доступен по HTTP на порту 8002. Добавьте следующую конфигурацию в Claude for Desktop:

```json
{
   "mcpServers": {
      "ticktick": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-everything", "http://localhost:8002/mcp"]
      }
   }
}
```

#### Docker команды для управления

```bash
# Просмотр логов
docker-compose logs -f ticktick-mcp

# Остановка сервиса
docker-compose down

# Перезапуск сервиса
docker-compose restart

# Обновление образа
docker-compose down
docker-compose build --no-cache
docker-compose up -d
```

#### Переменные окружения для Docker

| Переменная | Описание | По умолчанию |
|------------|----------|--------------|
| `SUPERGATEWAY_PORT` | Порт для HTTP доступа к MCP серверу | `8002` |
| `TICKTICK_ACCESS_TOKEN` | Access token для TickTick API | **Обязательно** |
| `TICKTICK_BASE_URL` | Base URL для TickTick API | `https://api.ticktick.com/open/v1` |
| `TICKTICK_CLIENT_ID` | Client ID (только для получения токена) | - |
| `TICKTICK_CLIENT_SECRET` | Client Secret (только для получения токена) | - |

#### Преимущества Docker запуска

- 🔒 **Изолированная среда** - сервер работает в отдельном контейнере
- 🌐 **HTTP доступ** - можно подключаться к серверу по сети
- 🔄 **Автоматический перезапуск** - контейнер перезапускается при сбоях
- 📦 **Простое развертывание** - один контейнер содержит все зависимости
- 🚀 **Масштабируемость** - легко запустить несколько экземпляров

#### Проверка работы Docker контейнера

```bash
# Проверка статуса контейнера
docker ps | grep ticktick-mcp

# Проверка доступности HTTP endpoint
curl http://localhost:8002/health

# Тест MCP подключения
curl -X POST http://localhost:8002/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}'
```

## Доступные MCP инструменты

### 📋 Управление проектами

#### `get_projects`
Получить все проекты пользователя TickTick
- **Параметры:** Нет параметров

#### `create_project`
Создать новый проект в TickTick
- **Параметры:**
  - `name` (обязательно) - Название проекта
  - `color` (опционально) - Цвет проекта (например, #FF0000)
  - `viewMode` (опционально) - Режим отображения: "list", "kanban", "timeline"
  - `sortOrder` (опционально) - Порядок сортировки проекта (число)
  - `kind` (опционально) - Тип проекта: "TASK" (по умолчанию) или "NOTE"

#### `update_project`
Обновить существующий проект в TickTick
- **Параметры:**
  - `projectId` (обязательно) - ID проекта
  - `name` (опционально) - Новое название проекта
  - `color` (опционально) - Новый цвет проекта (например, #FF0000)
  - `viewMode` (опционально) - Новый режим отображения: "list", "kanban", "timeline"
  - `sortOrder` (опционально) - Новый порядок сортировки проекта (число)
  - `kind` (опционально) - Новый тип проекта: "TASK" или "NOTE"

#### `delete_project`
Удалить проект из TickTick
- **Параметры:**
  - `projectId` (обязательно) - ID проекта

### ✅ Управление задачами

#### `get_project_tasks`
Получить все задачи конкретного проекта
- **Параметры:**
  - `projectId` (обязательно) - ID проекта

#### `get_task`
Получить детали конкретной задачи
- **Параметры:**
  - `projectId` (обязательно) - ID проекта
  - `taskId` (обязательно) - ID задачи

#### `create_task`
Создать новую задачу в TickTick
- **Параметры:**
  - `title` (обязательно) - Название задачи
  - `projectId` (обязательно) - ID проекта
  - `content` (опционально) - Описание задачи
  - `desc` (опционально) - Дополнительное описание
  - `isAllDay` (опционально) - Задача на весь день (boolean)
  - `startDate` (опционально) - Дата начала (ISO 8601 формат)
  - `dueDate` (опционально) - Срок выполнения (ISO 8601 формат)
  - `timeZone` (опционально) - Временная зона (например, America/Los_Angeles)
  - `reminders` (опционально) - Массив напоминаний (например, ['TRIGGER:P0DT9H0M0S'])
  - `repeatFlag` (опционально) - Правило повторения (например, 'RRULE:FREQ=DAILY;INTERVAL=1')
  - `priority` (опционально) - Приоритет: "none", "low", "medium", "high"
  - `sortOrder` (опционально) - Порядок сортировки (число)
  - `items` (опционально) - Массив подзадач:
    - `title` (обязательно) - Название подзадачи
    - `status` (опционально, по умолчанию 0) - Статус: 0=Normal, 1=Completed
    - `isAllDay` (опционально) - Подзадача на весь день
    - `startDate` (опционально) - Дата начала подзадачи
    - `timeZone` (опционально) - Временная зона подзадачи
    - `sortOrder` (опционально) - Порядок сортировки подзадачи

#### `update_task`
Обновить существующую задачу
- **Параметры:**
  - `taskId` (обязательно) - ID задачи
  - `projectId` (обязательно) - ID проекта
  - `title` (опционально) - Новое название задачи
  - `content` (опционально) - Новое описание задачи
  - `desc` (опционально) - Новое дополнительное описание
  - `isAllDay` (опционально) - Задача на весь день (boolean)
  - `startDate` (опционально) - Новая дата начала (ISO 8601 формат)
  - `dueDate` (опционально) - Новый срок выполнения (ISO 8601 формат)
  - `timeZone` (опционально) - Новая временная зона
  - `reminders` (опционально) - Новые напоминания
  - `repeatFlag` (опционально) - Новое правило повторения
  - `priority` (опционально) - Новый приоритет: "none", "low", "medium", "high"
  - `sortOrder` (опционально) - Новый порядок сортировки
  - `items` (опционально) - Подзадачи для обновления:
    - `id` (обязательно) - ID подзадачи (обязательно для обновления)
    - `title` (обязательно) - Название подзадачи
    - `status` (опционально, по умолчанию 0) - Статус подзадачи
    - `isAllDay` (опционально) - Подзадача на весь день
    - `startDate` (опционально) - Дата начала подзадачи
    - `timeZone` (опционально) - Временная зона подзадачи
    - `sortOrder` (опционально) - Порядок сортировки подзадачи

#### `complete_task`
Отметить задачу как выполненную
- **Параметры:**
  - `projectId` (обязательно) - ID проекта
  - `taskId` (обязательно) - ID задачи

#### `delete_task`
Удалить задачу из TickTick
- **Параметры:**
  - `projectId` (обязательно) - ID проекта
  - `taskId` (обязательно) - ID задачи

#### `get_all_projects_with_tasks`
Получить все проекты пользователя вместе со всеми задачами в каждом проекте
- **Параметры:** Нет параметров

## Доступные MCP ресурсы

### 📊 Статистика

#### `ticktick://stats`
Общая статистика по проектам и задачам
- Возвращает: JSON с общей статистикой (количество проектов, задач, выполненных, просроченных) и детальной статистикой по каждому проекту
- Включает: URI ресурса и временную метку

**Примечание**: Все инструменты используют токен доступа из переменной окружения `TICKTICK_ACCESS_TOKEN`.

## Примеры запросов для Claude

Вот несколько примеров запросов для использования с Claude после подключения TickTick MCP сервера:

### Базовые операции
- "Покажи мне все мои проекты TickTick"
- "Создай новую задачу 'Закончить документацию MCP сервера' в моем рабочем проекте с высоким приоритетом"
- "Покажи все задачи в моем личном проекте"
- "Отметь задачу 'Купить продукты' как выполненную"
- "Создай новый проект 'Планирование отпуска' с синим цветом"
- "Когда мой следующий дедлайн в TickTick?"

### Продвинутые сценарии
- "Создай план на завтра: утром проверить почту, в 10:00 встреча с командой, в 14:00 работа над проектом"
- "Покажи статус всех моих проектов и количество незавершенных задач в каждом"
- "Создай проект для планирования мероприятия со всеми необходимыми задачами"
- "Какие задачи просрочены и требуют внимания?"

## Приоритеты задач

Используйте строковые значения:
- `"none"` - Без приоритета (0)
- `"low"` - Низкий приоритет (1)
- `"medium"` - Средний приоритет (3)
- `"high"` - Высокий приоритет (5)

## Форматы дат

Все даты должны быть в формате ISO 8601:
```
2024-12-31T23:59:59Z
```

## Получение нового токена

Если ваш токен истек, просто запустите:

```bash
npm run get-token
```

Скрипт поднимет локальный сервер на порту 8080, откроет браузер для авторизации и автоматически получит новый токен.

Сервер обрабатывает обновление токенов автоматически, поэтому вам не нужно будет повторно аутентифицироваться, если вы не отзовете доступ или не удалите файл `.env`.

## Разработка

### Структура проекта

```
ticktick-mcp-ts/
├── src/
│   ├── client/
│   │   └── ticktick-client.ts    # Клиент для TickTick API с валидацией и retry логикой
│   ├── server/
│   │   └── ticktick-mcp-server.ts # MCP сервер с полным набором инструментов
│   ├── types/
│   │   └── ticktick.ts           # TypeScript типы и улучшенная обработка ошибок
│   ├── utils/
│   │   └── validators.ts         # Валидаторы для данных TickTick API
│   └── index.ts                  # Точка входа
├── get-token.ts                  # Скрипт для получения токена
├── test-server.ts                # Тест сервера
├── claude-desktop-config.json    # Пример конфигурации Claude
├── Dockerfile                    # Docker образ для контейнеризации
├── docker-compose.yml            # Docker Compose конфигурация
├── package.json
├── tsconfig.json
└── README.md
```

### Команды разработки

```bash
# Сборка
npm run build

# Запуск в режиме разработки
npm run dev

# Тестирование (с реальными API вызовами)
npm test

# Получение токена
npm run get-token

# Очистка
npm run clean

# Запуск сервера
npm start
```

### Процесс аутентификации

Проект реализует полный OAuth 2.0 поток для TickTick:

1. **Начальная настройка**: Пользователь предоставляет свой TickTick API Client ID и Secret
2. **Авторизация в браузере**: Пользователь перенаправляется в TickTick для предоставления доступа
3. **Получение токена**: Локальный сервер получает OAuth callback с кодом авторизации
4. **Обмен токена**: Код обменивается на токены доступа и обновления
5. **Хранение токена**: Токены безопасно сохраняются в локальном файле `.env`

Это упрощает пользовательский опыт, обрабатывая весь OAuth поток программно.

## Безопасность

- Никогда не коммитьте файл `.env` в репозиторий
- Храните токены доступа в безопасном месте
- Регулярно обновляйте токены доступа при необходимости
- Используйте переменные окружения для передачи токенов в продакшене

## Устранение неполадок

### Ошибки токена
```bash
# Если токен истек или недействителен
npm run get-token
```

### Проблемы с подключением
```bash
# Проверьте конфигурацию
npm test
```

### Проблемы с портом
Если порт 8080 занят, скрипт получения токена может не работать. Убедитесь, что порт свободен или измените его в `get-token.ts`.

---

## 🚀 Рекомендуем: polza.ai - Российский агрегатор API нейросетей

> **Недавно нашёл для себя очень годный инструмент** — российский сервис, который открывает API-доступ сразу к **сотням нейросетей**. Никаких VPN, никаких зарубежных карт — всё работает прямо из России! 🇷🇺

### 💡 Почему polza.ai?

**Для интеграторов и разработчиков:**
- 🔌 **Простое подключение** — понятная документация, быстрая интеграция
- 🛠️ **Совместимость с популярными инструментами** — n8n, Make, Zapier и другие
- 💰 **Выгодные тарифы** — реально экономичные цены на API вызовы
- 🏦 **Российская платёжная система** — работа с расчётного счёта, оплата в рублях


### 🎯 Примеры использования

Уже протестировал в нескольких автоматизациях:
- 📱 **Генерация контента для соцсетей** — автоматические посты и описания
- 🤖 **Telegram-боты с ИИ** — умные ответы и обработка запросов  
- 📧 **Обработка заявок с сайта** — автоматическая классификация и ответы
- 📬 **Email-рассылки** — персонализированные письма на основе ИИ

### 🔥 Что доступно

- **GPT-подобные модели** для генерации текста
- **Классификация и анализ** контента
- **Перевод** на множество языков
- **Анализ кода** и техническая документация
- **Скоро**: генерация изображений и видео! 🎨

### 👥 Для кого это особенно актуально

Если вы:
- 🔧 **Интегратор или фрилансер** — строите решения для клиентов
- 📈 **Маркетолог** — автоматизируете контент-процессы  
- 🏢 **Развиваете автоматизацию продаж** под ключ
- 💻 **Разработчик** — внедряете ИИ в проекты

**То polza.ai — это то, что вам нужно!**

### 🎉 Начните прямо сейчас

Если вы давно хотели внедрять нейросети в проекты, но вас останавливали VPN, карты и сложные подключения — **теперь всё решаемо**.

**[🔗 Перейти на polza.ai →](https://polza.ai)**

*Сервис полностью российский, удобный, выгодный и работает стабильно. Регистрируйтесь, тестируйте и начинайте строить свои AI-решения уже сейчас!*

---

## Содействие

Вклады приветствуются! Пожалуйста, не стесняйтесь отправлять Pull Request.

1. Форкните репозиторий
2. Создайте ветку для вашей функции (`git checkout -b feature/amazing-feature`)
3. Зафиксируйте ваши изменения (`git commit -m 'Add some amazing feature'`)
4. Отправьте в ветку (`git push origin feature/amazing-feature`)
5. Откройте Pull Request

## Лицензия

Этот проект лицензирован под MIT License

## Поддержка

Если у вас есть вопросы или проблемы, создайте issue в репозитории проекта.