Kaiten Server

Name: Kaiten Server
Availability: InStock
Author: vsaranyuk

FreeNot checked

MCP server for integrating Kaiten API with Claude Desktop, enabling management of cards, comments, spaces, and boards with advanced features like verbosity cont

by vsaranyuk

GitHub

About

MCP server for integrating Kaiten API with Claude Desktop, enabling management of cards, comments, spaces, and boards with advanced features like verbosity control, response format selection, and auto-truncation.

README

MCP сервер для интеграции Kaiten API с Claude Desktop. Позволяет управлять карточками, комментариями и пространствами Kaiten напрямую из Claude.

Возможности

Карточки: Чтение, создание, обновление, удаление, поиск
Комментарии: Полная работа с комментариями карточек
Пространства и доски: Навигация по структуре Kaiten
Поиск: Продвинутый поиск с фильтрами
Default Space: Автоматическая работа в выбранном пространстве
🎛️ Verbosity Control: Управление детализацией ответов (minimal/normal/detailed) - экономия до 90% токенов
📊 Response Formats: Выбор формата вывода (json/markdown) для разных сценариев
🛡️ Auto-truncation: Автоматическая защита от переполнения контекста (100k символов)
🧪 Evaluation Suite: Готовые шаблоны для тестирования качества работы
🔒 Production-Ready:
- Zod validation для всех параметров
- Автоматический retry с exponential backoff
- Concurrency control (rate limiting)
- LRU кеш с TTL для spaces/boards/users
- Расширенная обработка ошибок с hints
- Редакция токенов в логах
- Comprehensive logging & monitoring система

Быстрый старт

1. Установка

npm install

2. Настройка .env

Создайте файл .env:

cp .env.example .env

Заполните его вашими данными:

KAITEN_API_URL=https://your-domain.kaiten.ru/api/latest
KAITEN_API_TOKEN=your_api_token_here
KAITEN_DEFAULT_SPACE_ID=12345  # Ваш основной space_id

# Опциональные настройки производительности (значения по умолчанию)
KAITEN_MAX_CONCURRENT_REQUESTS=5     # Макс. одновременных запросов (1-20)
KAITEN_CACHE_TTL_SECONDS=300         # Время жизни кеша в секундах (0 = выкл.)
KAITEN_REQUEST_TIMEOUT_MS=10000      # Таймаут запроса в мс (1-60000)

Как получить API токен:

Войдите в Kaiten
Откройте настройки профиля
Создайте новый API токен
Скопируйте и вставьте в .env

3. Сборка

npm run build

4. Настройка Claude Desktop

Откройте конфигурационный файл:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Добавьте (замените путь на ваш полный путь):

{
  "mcpServers": {
    "kaiten": {
      "command": "node",
      "args": [
        "/полный/путь/к/MCP Kaiten/dist/index.js"
      ],
      "cwd": "/полный/путь/к/MCP Kaiten"
    }
  }
}

Альтернативный способ (без .env):

{
  "mcpServers": {
    "kaiten": {
      "command": "node",
      "args": ["/полный/путь/к/MCP Kaiten/dist/index.js"],
      "env": {
        "KAITEN_API_URL": "https://your-domain.kaiten.ru/api/latest",
        "KAITEN_API_TOKEN": "your_api_token_here",
        "KAITEN_DEFAULT_SPACE_ID": "12345"
      }
    }
  }
}

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

Полностью закройте (⌘+Q / Alt+F4) и откройте Claude Desktop заново.

6. Проверка

Напишите в Claude:

Покажи список пространств Kaiten

Доступные инструменты (26 tools)

Карточки

kaiten_get_card - Получить карточку по ID [format: json/markdown]
kaiten_create_card - Создать новую карточку
kaiten_update_card - Обновить карточку
kaiten_delete_card - Удалить карточку
kaiten_search_cards - Поиск карточек с фильтрами [verbosity: minimal/normal/detailed]
kaiten_get_space_cards - Получить карточки пространства [verbosity]
kaiten_get_board_cards - Получить карточки доски [verbosity]

Пространства и доски

kaiten_list_spaces - Список всех пространств
kaiten_get_space - Получить пространство [format: json/markdown]
kaiten_list_boards - Список досок [verbosity: minimal/normal/detailed]
kaiten_get_board - Получить доску [format: json/markdown]

Справочники (для корректных ID)

kaiten_list_columns - Список колонок (статусов) доски
kaiten_list_lanes - Список дорожек (lanes/swimlanes) доски
kaiten_list_types - Список типов карточек доски

Пользователи

kaiten_get_current_user - Получить текущего пользователя
kaiten_list_users - Список пользователей [verbosity: minimal/normal/detailed]

Управление кешем и диагностика

kaiten_cache_invalidate_spaces - Инвалидировать кеш пространств
kaiten_cache_invalidate_boards - Инвалидировать кеш досок
kaiten_cache_invalidate_users - Инвалидировать кеш пользователей
kaiten_cache_invalidate_all - Инвалидировать весь кеш
kaiten_get_status - Получить статус сервера (кеш, очередь, конфигурация, логирование, метрики)
kaiten_set_log_level - Изменить конфигурацию логирования в runtime

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

Базовые операции

Покажи карточку 789

Создай карточку "Исправить баг" на доске 456 с описанием "Проблема с авторизацией"

Обнови карточку 789: измени статус на 3

Добавь комментарий к карточке 789: "Работа завершена"

Verbosity Control - Экономия токенов

Minimal - Ультра-компактный формат (90% экономия):

Найди карточки на доске 456 с minimal verbosity
# Вывод: 1. [12345] Fix bug
#        2. [12346] Add feature

Normal - Сбалансированный (по умолчанию, 80% экономия):

Найди карточки на доске 456
# Вывод: полная информация с owner, board, статусом, URL

Detailed - Полный API response:

Найди карточки на доске 456 с detailed verbosity
# Вывод: все метаданные, permissions, внутренние поля

Когда использовать:

minimal - Быстрый поиск, получение ID, краткие списки
normal - Работа с карточками, обычные задачи (по умолчанию)
detailed - Отладка, интеграции, нужны все поля

Response Format Control

Markdown - Человеко-читаемый (по умолчанию):

Покажи карточку 12345
# Вывод: # Card Title
#        🔗 https://...
#        📋 Board: ...

JSON - Структурированные данные:

Покажи карточку 12345 в JSON формате
# Вывод: {"id": 12345, "title": "...", ...}

Когда использовать:

markdown - Показ пользователю, презентация (по умолчанию)
json - Интеграции, программная обработка, парсинг

Поиск

Найди карточки со словом "авторизация" на доске 456

Покажи мои карточки в пространстве 123

Найди все карточки в работе на доске 456

Default Space

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

Найди карточку про Болгарию
# Автоматически ищет в DEFAULT_SPACE_ID

Для поиска во всех пространствах явно укажите:

Найди карточку про Болгарию во ВСЕХ пространствах

Как работает Default Space:

Все card-операции автоматически используют KAITEN_DEFAULT_SPACE_ID
Для поиска в других пространствах укажите space_id явно
Для поиска везде явно попросите "во всех пространствах"

Оптимизация и производительность

✅ Лучшие практики поиска

DO (Делайте так):

Найди карточки "баг" на доске 456

DON'T (Не делайте так):

Покажи все карточки пространства и найди среди них "баг"

Параметры поиска

limit - количество карточек (по умолчанию 10)
sort_by - сортировка: created, updated, title
sort_direction - направление: asc, desc
condition - 1=активные (по умолчанию), 2=архивные

Примеры с параметрами

Найди 20 карточек на доске 456

Покажи архивные карточки на доске 456

Найди карточки на доске 456, отсортированные по дате обновления

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

MCP Kaiten/
├── src/
│   ├── index.ts          # MCP сервер
│   ├── kaiten-client.ts  # Kaiten API клиент
│   ├── config.ts         # Конфигурация и валидация
│   ├── cache.ts          # LRU кеш
│   ├── schemas.ts        # Zod схемы валидации
│   ├── utils.ts          # Utility functions (11 helpers)
│   ├── logging/          # Система логирования
│   │   ├── index.ts      # Экспорты
│   │   ├── types.ts      # TypeScript типы
│   │   ├── logger.ts     # Unified logger (singleton)
│   │   ├── file-logger.ts    # Pino file logger
│   │   ├── mcp-logger.ts     # MCP notifications logger
│   │   └── metrics.ts        # Performance metrics collector
│   └── middleware/       # HTTP middleware
│       └── logging-middleware.ts  # Axios logging interceptor
├── evaluations/          # Evaluation suite
│   ├── README.md         # Руководство по evaluations
│   └── kaiten-eval-template.xml  # Шаблон с 10 вопросами
├── logs/                 # Файлы логов (в .gitignore)
├── dist/                 # Скомпилированные файлы
├── .env                  # Конфигурация (не в git)
├── .env.example          # Пример конфигурации
├── tsconfig.json         # TypeScript конфигурация
├── package.json
├── README.md             # Этот файл
├── CHANGELOG.md          # История изменений
└── CLAUDE.md             # Инструкции для Claude Code

Возможности карточек

При получении карточки возвращаются следующие поля:

{
  "id": 12345,
  "title": "Название карточки",
  "url": "https://your-domain.kaiten.ru/space/12345/card/12345",
  "description": "Полное описание...",
  "created": "2025-07-23T07:55:52.934Z",
  "updated": "2025-10-01T12:14:47.754Z",
  "state": 2,
  "owner_id": 67890,
  "owner_name": "Иван Иванов",
  "board_id": 54321,
  "board_title": "Project Board",
  "blocked": true,
  "block_reason": "Ожидание данных от команды",
  "blocked_at": "2025-08-04T09:10:22.528Z",
  "blocker_name": "Иван Иванов",
  "archived": false,
  "tags": ["важно", "срочно"],
  "members": ["Иван Иванов", "Мария Петрова"],
  "due_date": "2025-10-19T00:00:00.000Z"
}

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

Сервер не подключается

Проверьте правильность пути в конфигурации Claude
Убедитесь, что проект собран: npm run build
Проверьте .env файл
Перезапустите Claude Desktop полностью (⌘+Q)

Ошибки API

Проверьте, что токен действителен
URL должен заканчиваться на /api/latest
Проверьте права доступа токена в настройках Kaiten

Ошибка "Tool result is too large"

Используйте фильтры и параметр board_id:

# Плохо
Найди карточки в пространстве 123

# Хорошо
Найди карточки на доске 456 в пространстве 123

Отладка

Продвинутое логирование

Сервер поддерживает гибкую систему логирования для отладки и мониторинга. Все настройки логирования можно контролировать через переменные окружения или в runtime с помощью инструмента kaiten_set_log_level.

Переменные окружения (опционально):

# Включить/выключить логирование (по умолчанию: true)
KAITEN_LOG_ENABLED=true

# Уровень логирования (по умолчанию: error)
# debug | info | notice | warning | error | critical | alert | emergency
KAITEN_LOG_LEVEL=error

# Отправлять логи в MCP клиент (по умолчанию: false)
KAITEN_LOG_MCP_ENABLED=false

# Записывать логи в файл (по умолчанию: false)
KAITEN_LOG_FILE_ENABLED=false

# Путь к файлу логов (по умолчанию: ./logs/kaiten-mcp.log)
KAITEN_LOG_FILE_PATH=./logs/kaiten-mcp.log

# Логировать все HTTP запросы (по умолчанию: false)
KAITEN_LOG_REQUESTS=false

# Собирать метрики производительности (по умолчанию: false)
KAITEN_LOG_METRICS=false

Готовые профили:

Production (минимальное логирование):

KAITEN_LOG_LEVEL=error
KAITEN_LOG_FILE_ENABLED=false
KAITEN_LOG_REQUESTS=false
KAITEN_LOG_METRICS=false

Development (умеренное логирование для отладки):

KAITEN_LOG_LEVEL=info
KAITEN_LOG_FILE_ENABLED=true
KAITEN_LOG_REQUESTS=false
KAITEN_LOG_METRICS=true

Debug (полное логирование для глубокого анализа):

KAITEN_LOG_LEVEL=debug
KAITEN_LOG_MCP_ENABLED=true
KAITEN_LOG_FILE_ENABLED=true
KAITEN_LOG_REQUESTS=true
KAITEN_LOG_METRICS=true

Runtime управление логированием:

Используйте инструмент kaiten_set_log_level для изменения конфигурации без перезапуска:

# Включить debug режим
Установи уровень логирования debug с файлами и метриками

# Выключить всё логирование
Установи уровень логирования off

# Включить только метрики производительности
Установи уровень логирования info с метриками

Просмотр логов:

Логи сервера выводятся в stderr. На macOS/Linux их можно посмотреть через Console.app или запустив Claude из терминала. Файловые логи находятся в директории logs/ в формате JSON (для дальнейшего анализа).

Метрики производительности:

При включенных метриках (KAITEN_LOG_METRICS=true) используйте kaiten_get_status для просмотра:

Покажи статус сервера

Метрики включают:

Общее количество запросов
Агрегированная статистика по инструментам (latency, success rate, cache hit rate)
Последние 100 запросов с деталями

Технические детали

Node.js: Версия 20 или выше (требование engines)
TypeScript: 5.0+
MCP SDK: @modelcontextprotocol/sdk v1.20.0
API Client: axios с retry/backoff и AbortSignal support
Размер: ~600 строк TypeScript, 25KB скомпилированного кода

MCP I/O Protocol

Критично для отладки: MCP использует stdio-транспорт для общения между клиентом и сервером.

stdout — только JSON-RPC протокольные сообщения (чистый канал связи)
stderr — все логи, дебаг-информация, ошибки

Важно:

Любой console.log() в коде нарушает протокол → используйте console.error() для логов
Этот сервер гарантирует чистоту stdout через safeLog wrapper (src/config.ts:126-152)
При отладке смотрите stderr: node dist/index.js 2>debug.log или используйте MCP Inspector

Подробнее: Build an MCP server

Лицензия

MIT

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

CHANGELOG.md - История изменений
CLAUDE.md - Инструкции для Claude Code разработки
evaluations/README.md - Руководство по evaluation suite
Kaiten API Docs - Официальная документация API

How to install

Run in your terminal:

claude mcp add kaiten-mcp-server -- npx

Command Palette