# Kaiten MCP Server

> MCP-сервер для работы с задачами [Kaiten](https://kaiten.ru/) через AI-агентов (Claude Code, Claude Desktop и др.)

[![Tests](https://img.shields.io/badge/tests-78%20passed-brightgreen)](./STATUS.md)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.26+-orange)](https://github.com/modelcontextprotocol)

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

Kaiten MCP Server предоставляет AI-агентам (Claude) доступ к вашим задачам в Kaiten через [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).

**Реализованные инструменты:**

- ✅ **get-task-details** — получение детальной информации о задаче (описание, комментарии, участники)
- ✅ **get-task-status** — быстрая проверка статуса одной или нескольких задач
- ✅ **get-time-logs** — учёт времени по задаче с группировкой по пользователям/дням
- ✅ **create-task** — создание новых задач на доске
- ✅ **update-task** — обновление существующих задач (заголовок, описание, перемещение, назначение)

**В разработке (roadmap):**
- 🔥 **get-board-cards** — список задач на доске с фильтрацией (критично)
- **get-board-structure** — структура доски (колонки, лейны, теги)
- **delete-task**, **add-comment**, **log-time** и [другие фичи](./specs/roadmap.md)

## 📋 Требования

- **Node.js** >= 20
- **Kaiten API токен** (создаётся в профиле: Настройки → API-токены)
- **Доступ к Kaiten API** вашей организации

## 🚀 Установка

### 1. Клонирование и сборка

```bash
git clone git@github.com:Happiest-d/kaiten-mcp.git
cd kaiten-mcp
npm install
npm run build
```

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

Требуются две переменные:

| Переменная | Описание | Пример |
|------------|----------|--------|
| `KAITEN_API_TOKEN` | API-токен из профиля Kaiten | `abc123def456...` |
| `KAITEN_BASE_URL` | Полный URL API вашего Kaiten | `https://mycompany.kaiten.ru/api/latest` |

**Получение токена:**
1. Откройте Kaiten
2. Профиль → Настройки → API-токены
3. Создать новый токен

### 3. Подключение к Claude Code

Добавьте в `~/.claude/mcp.json` или `.mcp.json` вашего проекта:

```json
{
  "mcpServers": {
    "kaiten": {
      "command": "node",
      "args": ["/path/to/kaiten-mcp/dist/src/index.js"],
      "env": {
        "KAITEN_API_TOKEN": "ваш_токен",
        "KAITEN_BASE_URL": "https://yourcompany.kaiten.ru/api/latest"
      }
    }
  }
}
```

**Для Claude Desktop** используйте аналогичную конфигурацию в настройках приложения.

После перезапуска Claude получит доступ ко всем MCP tools для работы с Kaiten.

## 🛠️ Доступные инструменты (MCP Tools)

### `get-task-details`

Получает детальную информацию о задаче: описание, участников, комментарии, метаданные.

```json
{
  "card_id": 12345,
  "include_comments": true,
  "comments_limit": 20
}
```

**Возвращает:** title, description, state, owner, members, tags, comments (с пагинацией), created_at, updated_at

### `get-task-status`

Быстрая проверка статуса задач (до 50 за раз).

```json
{
  "card_ids": [12345, 67890]
}
```

**Возвращает:** card_id, title, board_id, column_id, state, updated_at для каждой карточки

### `get-time-logs`

Получает логи учёта времени по задаче с группировкой.

```json
{
  "card_id": 12345,
  "group_by": "user"
}
```

**Режимы группировки:**
- `"none"` — плоский список всех записей
- `"user"` — группировка по пользователям
- `"date"` — группировка по дням

**Возвращает:** total_minutes, entries (с деталями: user_id, time_spent, for_date, comment)

### `create-task`

Создаёт новую задачу на доске.

```json
{
  "title": "Исправить баг авторизации",
  "description": "Пользователи не могут войти через OAuth...",
  "board_id": 1660008,
  "column_id": 5747562,
  "position": 1
}
```

**Возвращает:** card_id, title, board_id, column_id, state, created_at

### `update-task`

Обновляет существующую задачу (заголовок, описание, перемещение, назначение).

```json
{
  "card_id": 12345,
  "title": "Новый заголовок",
  "column_id": 5747563,
  "owner_id": 501
}
```

**Поддерживаемые обновления:**
- Переименование (`title`)
- Изменение описания (`description`)
- Перемещение между колонками (`column_id`)
- Перемещение между лейнами (`lane_id`)
- Переназначение исполнителя (`owner_id`)
- Изменение участников (`members`)
- Изменение тегов (`tags`)

**Возвращает:** полную обновлённую карточку со всеми полями

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

```
kaiten-mcp/
├── src/
│   ├── index.ts              # Точка входа MCP сервера
│   ├── server.ts             # Конфигурация и регистрация tools
│   ├── kaiten/
│   │   ├── client.ts         # HTTP-клиент для Kaiten API
│   │   └── types.ts          # TypeScript типы и маппинги
│   └── tools/                # MCP tools (один файл = один tool)
│       ├── get-task-details.ts
│       ├── get-task-status.ts
│       ├── get-time-logs.ts
│       ├── create-task.ts
│       └── update-task.ts
├── tests/                    # Unit-тесты (Vitest)
│   ├── kaiten/
│   └── tools/
├── specs/                    # Спецификации фич
│   ├── roadmap.md            # Полный roadmap проекта
│   └── *.md                  # Детальные спеки по каждой фиче
├── MANUAL.md                 # Пользовательская документация
├── STATUS.md                 # Текущий статус проекта (фичи, тесты)
└── CLAUDE.md                 # Стандарты разработки, TDD, архитектура
```

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

### Запуск тестов

```bash
npm test                # Все тесты (78 тестов)
npm test -- get-task    # Конкретный файл
```

**Текущий статус:** 78/78 тестов проходят ✅

### Сборка

```bash
npm run build           # Компиляция TypeScript
npm run lint            # ESLint проверка
```

### Методология: TDD (Test-Driven Development)

Проект следует строгому TDD циклу:

1. **RED** — сначала пишется падающий тест
2. **GREEN** — пишется минимальный код для прохождения теста
3. **REFACTOR** — рефакторинг с сохранением зелёных тестов

Каждая фича начинается со спецификации в `specs/`, затем пишутся тесты, затем реализация.

### Стек

- **TypeScript** (strict mode)
- **MCP SDK** v1.26+ (Model Context Protocol)
- **Zod v4** — валидация схем
- **Vitest** — тестирование
- **ESLint** — линтинг

## 📚 Документация

- **[MANUAL.md](./MANUAL.md)** — подробное руководство пользователя (параметры, примеры)
- **[STATUS.md](./STATUS.md)** — текущий статус фич, тестов, инфраструктуры
- **[CLAUDE.md](./CLAUDE.md)** — стандарты кода, архитектура, TDD workflow
- **[specs/roadmap.md](./specs/roadmap.md)** — полный roadmap с 17 фичами и приоритетами

## 🗺️ Roadmap

**Реализовано (5/17 фич):**
- ✅ get-task-details, get-task-status, get-time-logs
- ✅ create-task, update-task

**В приоритете:**
1. 🔥 **get-board-cards** — список задач на доске с фильтрацией (критично для навигации)
2. **get-board-structure** — структура доски (колонки, лейны, теги)
3. **delete-task** / **archive-task** — удаление/архивация задач
4. **add-comment** — добавление комментариев
5. **log-time** — учёт времени

Полный список: [specs/roadmap.md](./specs/roadmap.md)

## 📝 Лицензия

MIT

## 🤝 Контрибуция

Проект следует строгим стандартам TDD и spec-driven development:

1. Создать issue с описанием фичи
2. Написать спецификацию в `specs/`
3. Написать тесты (RED фаза)
4. Реализовать фичу (GREEN фаза)
5. Отрефакторить (REFACTOR фаза)
6. Создать PR с обновлённой документацией (STATUS.md, MANUAL.md)

См. [CLAUDE.md](./CLAUDE.md) для деталей.

---

**Made with ❤️ for AI agents**