Kaiten MCP Server

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

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

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

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

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

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 циклу:

1. RED — сначала пишется падающий тест
2. GREEN — пишется минимальный код для прохождения теста
3. 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

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

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

Полный список: 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 для деталей.

---

Made with ❤️ for AI agents