使用说明
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 |
Получение токена:
- Откройте 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
