Kaiten MCP Server

MCP-сервер для работы с задачами Kaiten через AI-агентов (Claude Code, Claude Desktop и др.)

![Tests](./STATUS.md) ![TypeScript](https://www.typescriptlang.org/) ![MCP SDK](https://github.com/modelcontextprotocol)

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

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

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

✅ 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 и другие фичи

📋 Требования

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

🚀 Установка

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

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 |

Получение токена:

Откройте Kaiten
Профиль → Настройки → API-токены
Создать новый токен

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

Добавьте в ~/.claude/mcp.json или .mcp.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`

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

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

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

`get-task-status`

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

{
  "card_ids": [12345, 67890]
}

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

`get-time-logs`

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

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

Режимы группировки:

"none" — плоский список всех записей
"user" — группировка по пользователям
"date" — группировка по дням

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

`create-task`

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

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

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

`update-task`

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

{
  "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, архитектура

🧪 Разработка

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

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

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

Сборка

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

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

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

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

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

Стек

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

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

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

🗺️ Roadmap

Реализовано (5/17 фич):

✅ get-task-details, get-task-status, get-time-logs
✅ create-task, update-task

В приоритете:

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

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

📝 Лицензия

MIT

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

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

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

См. CLAUDE.md для деталей.

---

Made with ❤️ for AI agents

kaiten-mcp