Kaiten MCP

MCP Server и CLI-инструмент для работы с Kaiten API с оптимизацией токенов.

📑 Содержание

Установка
Конфигурация
Использование
Оптимизация токенов
Все доступные команды
Для AI помощников
Troubleshooting
Инструкции для AI

Установка

git clone https://github.com/tyunn/kaiten-mcp.git
cd kaiten-mcp

Конфигурация

Настройки проекта (опционально)

Обязательные настройки

Создайте глобальный конфиг с настройками доступа:

mkdir -p ~/.kaiten
cat > ~/.kaiten/config << EOF
KAITEN_API_URL=https://ваш-домен.kaiten.ru/api/latest
KAITEN_API_TOKEN=ваш_api_токен
EOF

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

API URL: это адрес вашего пространства Kaiten (например: https://company.kaiten.ru/api/latest)
API Token: зайдите в настройки профиля в Kaiten → "API токены" → создайте новый токен

Важно: Этот файл содержит секретные данные (токен доступа) и НЕ должен коммититься в git.

Создайте файл .kaiten.env в директории вашего проекта для бизнес логики проекта:

# Скопируйте пример и отредактируйте под ваш проект
cp .kaiten.config.example .kaiten.env

Пример содержимого .kaiten.env:

# Kaiten project configuration

# Пространство по умолчанию
# Все операции с карточками будут использовать это пространство
KAITEN_DEFAULT_SPACE_ID=12345

# Доска по умолчанию
# Все операции создания карточек будут использовать эту доску
KAITEN_DEFAULT_BOARD_ID=67890

# Временная директория для скачивания файлов
# Файлы сохраняются в /tmp/kaiten/{cardId}/ по умолчанию
KAITEN_TEMP_DIR=/tmp/kaiten

Параметры ограничения доступа (опционально):

# Список разрешённых пространств (через запятую)
# Полезно для команд которые работают с несколькими проектами
KAITEN_ALLOWED_SPACE_IDS=12345,67890

# Список разрешённых досок (через запятую)
# Полезно для ограничения доступа к конкретным доскам
KAITEN_ALLOWED_BOARD_IDS=111,222,333

Уровень логирования (опционально):

# Уровень логирования для MCP сервера
# error - только ошибки
# warn - предупреждения и ошибки
# info - информационные сообщения (по умолчанию)
# debug - все сообщения включая детальные данные запросов/ответов
KAITEN_LOG_LEVEL=info

Порядок загрузки конфигурации

SDK ищет конфигурацию в следующем приоритете:

~/.kaiten/config (глобальная) ← загружается первой
.kaiten.env (проектная) ← загружается второй
.env (fallback) ← загружается третьей, только если нет KAITEN_API_URL

Важно:

Глобальные настройки (~/.kaiten/config) обязательны
Проектные настройки (.kaiten.env) используются для Space ID и Board ID
Параметр cwd в MCP config определяет директорию проекта для поиска .kaiten.env
Board ID можно узнать через команду npm start board
Ограничения работают на уровне SDK и защищают от случайного доступа к другим пространствам/доскам

Использование

Через MCP server (AI assistants)

Команды доступны для AI ассистентов через MCP server. AI может вызывать их напрямую без префикса kaiten.

Команды CLI (для локального использования)

# Поиск задач (оптимизировано для токенов)
npm start find agent-safe                           # ~30 байт
npm start find agent-safe -m                         # ~81 байт (JSON)
npm start find agent-safe --board="Название доски"  # Фильтр по доске

# Детали задач
npm start card-simple <id>                           # ~200 байт
npm start card <id>                                  # Полный JSON

# CRUD операций
npm start create '{"title":"Задача","boardId":123,"columnId":456}'
npm start update <id> '{"title":"Новое название"}'
npm start delete <id>
npm start move <id> <column_id>
npm start assign <id> <user_id>

# Подзадачи и комментарии
npm start subtask create <parent_id> <title>
npm start comment add <card_id> <text>

# Метки
npm start tag add <card_id> <tag_name>
npm start tag filter <tag_name> -m

# Навигация
npm start board                 # Список досок
npm start column <board_id>      # Список колонок
npm start user [query]           # Поиск пользователя

# Справка
npm start help

Глобальное использование CLI (опционально)

npm install -g .

После этого можно использовать команды без npm start:

kaiten find agent-safe
kaiten card-simple 12345

Использование SDK в проектах

import { createSDK } from 'kaiten-cli';

const sdk = createSDK();

// Получить карточку
const card = await sdk.getCard(12345);

// Создать карточку
const newCard = await sdk.createCard({
  title: 'Новая задача',
  boardId: 123,
  columnId: 456,
  tags: ['agent-safe']
});

// Создать подзадачи
await sdk.createTaskFlow(parentCardId, [
  { title: 'Подзадача 1', description: '...' },
  { title: 'Подзадача 2', description: '...' }
]);

// Переместить карточку
await sdk.moveToColumn(cardId, columnId);

// Добавить комментарий
await sdk.addComment(cardId, 'Текст комментария');

// Проверить метки
if (sdk.hasTag(card, 'agent-safe')) {
  // Работаем с задачей
}

// Поиск по меткам
const agentSafeCards = await sdk.getCardsWithTag('agent-safe');

🎯 Оптимизация токенов

Сравнение команд:

Команда	Размер (байт)	Использование
`kaiten find agent-safe`	30	Поиск задач для агента
`kaiten find agent-safe -m`	81	Поиск с JSON
`kaiten card-simple <id>`	200	Детали задачи
`kaiten tag filter agent-safe`	100	Поиск по метке
`kaiten simple`	2924	❌ Все задачи
`kaiten cards`	5958	❌ Все задачи JSON

Что оптимизировано:

Удалены base64 аватары
Убраны избыточные метаданные
Оптимизированы форматы дат и времени (YYYY-MM-DD)
Сокращены описания до 500 символов
Минимальный JSON с короткими ключами (i, t, c, tg)

Все доступные команды

Карточки

Команда	Описание
`find <tag> [-m] [--board=<id>]`	Быстрый поиск по метке (~30 байт)
`card-simple <id>`	Детали задачи (человекочитаемый)
`card <id>`	Детали задачи (JSON)
`cards`	Список задач (JSON)
`simple`	Список задач (человекочитаемый)
`create '<json>'`	Создать карточку
`update <id> '<json>'`	Обновить карточку
`delete <id>`	Удалить карточку
`move <id> <column_id> [lane_id]`	Переместить карточку
`assign <id> <user_id>`	Назначить исполнителя

Git интеграция

Команда	Описание
`git-branch <card_id>`	Создать ветку для задачи (feature/-<title>)
`git-checkout <card_id>`	Переключиться на ветку задачи
`git-commit <card_id> [msg]`	Закоммитить (msg по умолчанию: "Work in progress")
`git-status`	Показать статус git
`git-push <card_id>`	Запушить ветку

Подзадачи и комментарии

Команда	Описание
`subtask create <parent> <title>`	Создать подзадачу
`subtask list <parent>`	Список подзадач
`subtask attach <card> <parent>`	Привязать к родителю
`subtask detach <card>`	Отвязать от родителя
`comment add <card> <text>`	Добавить комментарий
`comment list <card>`	Список комментариев

Метки

Команда	Описание
`tag add <id> <tag>`	Добавить метку
`tag remove <id> <tag>`	Удалить метку
`tag filter <tag> [-m]`	Фильтр по метке
`tag list`	Список карточек с метками

Файлы

Команда	Описание
`kaiten_get_files <card_id>`	Список файлов карточки
`kaiten_download_file <card_id> <file_id> [dir]`	Скачать файл в временную директорию
`kaiten_download_all_files <card_id> [dir]`	Скачать все файлы карточки
`kaiten_clean_temp [dir]`	Очистить временную директорию

Файлы сохраняются в /tmp/kaiten/{cardId}/ по умолчанию. Директорию можно изменить через параметр dir или переменную окружения KAITEN_TEMP_DIR.

Флаги

Флаг	Описание
`-m, --minimal`	Минимальный JSON (без отступов, короткие ключи)
`--board=<id	name>`

Git интеграция (опционально)

npm start git-branch <card_id>             # Создать ветку для задачи
npm start git-checkout <card_id>           # Переключиться на ветку задачи
npm start git-commit <card_id> [msg]       # Закоммитить изменения
npm start git-status                       # Показать статус git
npm start git-push <card_id>                # Запушить ветку

Использование SDK в проектах (опционально)

import { createSDK } from 'kaiten-cli';

const sdk = createSDK();

// Получить карточку
const card = await sdk.getCard(12345);

// Создать карточку
const newCard = await sdk.createCard({
  title: 'Новая задача',
  boardId: 123,
  columnId: 456,
  tags: ['agent-safe']
});

// Создать подзадачи
await sdk.createTaskFlow(parentCardId, [
  { title: 'Подзадача 1', description: '...' },
  { title: 'Подзадача 2', description: '...' }
]);

// Переместить карточку
await sdk.moveToColumn(cardId, columnId);

// Добавить комментарий
await sdk.addComment(cardId, 'Текст комментария');

// Проверить метки
if (sdk.hasTag(card, 'agent-safe')) {
  // Работаем с задачей
}

// Поиск по меткам
const agentSafeCards = await sdk.getCardsWithTag('agent-safe');

Архитектура

Структура

src/
├── sdk.js              # Высокоуровневый SDK
├── api/
│   ├── cards.js      # CRUD карточек
│   ├── subtasks.js   # Подзадачи
│   ├── comments.js   # Комментарии
│   ├── columns.js    # Доски и колонки
│   ├── users.js      # Пользователи
│   ├── client.js     # HTTP клиент (axios)
│   └── index.js      # Экспорт API
└── utils/
    ├── config.js     # Загрузка конфигурации
    └── temp.js      # Управление временной директорией для файлов

Конфигурация (приоритет):

~/.kaiten/config - глобальные настройки (API URL, токен)
.kaiten.env - проектные настройки (Space ID, Board ID)
.env (fallback) - для обратной совместимости

Для AI помощников

Настройка MCP server

Добавьте сервер Kaiten MCP в конфигурацию вашего AI-ассистента.

Для Claude Code (терминал)

Используйте команду claude mcp add для добавления сервера:

# Глобально (для всех проектов)
claude mcp add kaiten /путь/к/kaiten-mcp/start-mcp.sh

# Или локально для конкретного проекта
claude mcp add kaiten /путь/к/kaiten-mcp/start-mcp.sh -s local

Проверка:

claude mcp list

Вывод должен показать:

Checking MCP server health...
kaiten: /путь/к/kaiten-mcp/start-mcp.sh - ✓ Connected

Важно: После добавления MCP сервера перезапустите сессию Claude Code, чтобы инструменты стали доступны.

Для других AI-ассистентов

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

Cursor:

Проектный: <ваш-проект>/.cursor/mcp.json
Глобальный: ~/.cursor/mcp.json

Continue.dev:

Проектный: <ваш-проект>/.continue/config.json
Глобальный: ~/.continue/config.json

Настройка проекта

В директории вашего проекта создайте файл конфигурации Kaiten:

Файл .kaiten.env в корне проекта:

# Kaiten project configuration
KAITEN_DEFAULT_SPACE_ID=12345
KAITEN_DEFAULT_BOARD_ID=67890

# Опционально: ограничение доступа для безопасности
KAITEN_ALLOWED_SPACE_IDS=12345
KAITEN_ALLOWED_BOARD_IDS=67890

Глобальный файл ~/.kaiten/config:

# Обязательные параметры
KAITEN_API_URL=https://ваш-домен.kaiten.ru/api/latest
KAITEN_API_TOKEN=ваш_api_токен

Важные моменты

Параметр cwd в конфигурации MCP определяет директорию проекта для поиска .kaiten.env
Без cwd будут использоваться только глобальные настройки из ~/.kaiten/config
Параметры доступа (KAITEN_ALLOWED_*) работают только если указаны в .kaiten.env проекта

Инструкции для AI assistants

В каждом проекте создайте файл CLAUDE.md в корневой директории для инструкций AI (Claude Code, Cursor и др.).

Добавьте в CLAUDE.md вашего проекта:

Настройка MCP server

Добавьте в конфигурацию Claude Code:

{
  "mcpServers": {
    "kaiten": {
      "command": "/путь/к/kaiten-mcp/start-mcp.sh"
    }
  }
}

🔧 Troubleshooting

MCP инструменты не доступны

Симптом: Вы добавили MCP сервер, но AI не видит инструменты kaiten_*.

Решения:

Проверьте конфигурацию:
```
claude mcp list
```
Должен показать статус ✓ Connected.
Перезапустите Claude Code:
- После добавления MCP сервера закройте и откройте Claude Code
- Или перезапустите терминальную сессию

Используйте правильную команду добавления:

# Для Claude Code в терминале
claude mcp add kaiten /путь/к/kaiten-mcp/start-mcp.sh

# Проверьте список
claude mcp list

Удалите старые конфигурации: Если раньше использовали .claude/settings.json, удалите его:
```
rm .claude/settings.json
claude mcp add kaiten /путь/к/start-mcp.sh
```

Ошибка "No MCP servers configured"

Симптом: Команда claude mcp list показывает "No MCP servers configured".

Решение:

# Добавьте сервер снова
claude mcp add kaiten /путь/к/kaiten-mcp/start-mcp.sh

# Проверьте результат
claude mcp list

MCP сервер не запускается

Симптом: Статус показывает "✗ Connection failed".

Проверки:

Права доступа:

chmod +x /путь/к/kaiten-mcp/start-mcp.sh

Путь к Node.js:

which node
# Должен показать путь к node

Тест ручного запуска:

/путь/к/kaiten-mcp/start-mcp.sh
# Должен запуститься без ошибок

Конфигурация не загружается

Симптом: SDK не видит настройки из .kaiten.env.

Решение:

Проверьте наличие файла:
```
ls -la .kaiten.env
```
Проверьте приоритет загрузки: SDK ищет конфигурацию в таком порядке:
1. ~/.kaiten/config (глобальная)
2. .kaiten.env (проектная)
3. .env (fallback)

Тест загрузки:

node -e "
import { getConfig } from '/путь/к/kaiten-mcp/src/utils/config.js';
const config = getConfig();
console.log('API URL:', config.apiUrl ? '✓' : '✗');
console.log('API Token:', config.apiToken ? '✓' : '✗');
console.log('Space ID:', config.defaultSpaceId);
console.log('Board ID:', config.defaultBoardId);
"

Альтернатива: Прямое использование SDK

Если MCP не работает, можно использовать SDK напрямую:

node -e "
import { createSDK } from '/путь/к/kaiten-mcp/src/sdk.js';
const sdk = createSDK();
sdk.getCardsWithTag('agent-safe').then(cards => {
  console.log('Найдено:', cards.length, 'карточек');
  console.log(JSON.stringify(cards, null, 2));
}).catch(err => console.error('Ошибка:', err.message));
"

Преимущества прямого использования SDK:

Работает без MCP интеграции
Полный доступ ко всем функциям
Легко тестировать и отлаживать

Недостатки:

Не интегрирован с AI ассистентами
Требует Node.js
Нет автоматической документации инструментов

Инструкции для AI

В каждом проекте создайте файл CLAUDE.md в корневой директории для инструкций AI (Claude Code, Cursor и др.).

Добавьте в CLAUDE.md вашего проекта:

## Работа с Kaiten

Когда я прошу посмотреть карточки, тикеты или задачи в Kaiten - используй MCP инструменты напрямую.

**Важно**: Перед началом работы проверяй метки карточки. Работай только с задачами, у которых есть метка `agent-safe`. Если у задачи есть метка `human-review-required` - не мерь её автоматически, требуй ручного просмотра.

**Минимизация токенов**: Используй фильтрацию по меткам вместо получения всех задач.

### Доступные MCP инструменты

**Поиск карточек:**
- `kaiten_find_cards` с параметром `tagName: "agent-safe"` - Найти карточки по метке
- `kaiten_card` с параметром `cardId: <id>, simple: true` - Детали карточки (человекочитаемый)
- `kaiten_card` с параметром `cardId: <id>` - Детали карточки (JSON)

**Навигация:**
- `kaiten_spaces` - Список пространств
- `kaiten_boards` с параметром `spaceId: <id>` - Список досок
- `kaiten_columns` с параметром `boardId: <id>` - Список колонок

**CRUD операции:**
- `kaiten_create_card` с параметрами `title, boardId, columnId, [description], [laneId]` - Создать карточку. **Рекомендуется указывать `laneId`**, иначе карточка попадёт на дефолтную lane доски.
- `kaiten_update_card` с параметрами `cardId, data` - Обновить карточку
- `kaiten_delete_card` с параметром `cardId` - Удалить карточку
- `kaiten_move_card` с параметрами `cardId, columnId, [laneId]` - Переместить карточку
- `kaiten_assign_card` с параметрами `cardId, userId` - Назначить исполнителя

**Дочерние карточки и комментарии:**
- `kaiten_create_child_card` с параметрами `parentId, title` - Создать дочернюю карточку
- `kaiten_get_child_cards` с параметром `cardId` - Список дочерних карточек
- `kaiten_get_all_child_cards` с параметром `cardId` - Список всех дочерних карточек (включая вложенные)
- `kaiten_get_parent` с параметром `cardId` - Получить родительскую карточку
- `kaiten_attach_to_parent` с параметрами `cardId, parentId, position` - Привязать карточку к родителю
- `kaiten_detach_from_parent` с параметром `cardId` - Отвязать карточку от родителя
- `kaiten_add_comment` с параметрами `cardId, text` - Добавить комментарий
- `kaiten_get_comments` с параметром `cardId` - Список комментариев

**Метки:**
- `kaiten_add_tag` с параметрами `cardId, tagName` - Добавить метку
- `kaiten_remove_tag` с параметрами `cardId, tagName` - Удалить метку

**Файлы:**
- `kaiten_get_files` с параметром `cardId` - Список файлов карточки
- `kaiten_download_file` с параметрами `cardId, fileId, [dir]` - Скачать файл в временную директорию
- `kaiten_download_all_files` с параметром `cardId, [dir]` - Скачать все файлы карточки
- `kaiten_clean_temp` с параметром `[dir]` - Очистить временную директорию

**Git интеграция:**
- `kaiten_git_branch` с параметром `cardId` - Создать ветку для задачи
- `kaiten_git_checkout` с параметром `cardId` - Переключиться на ветку задачи
- `kaiten_git_commit` с параметрами `cardId, message` - Закоммитить изменения
- `kaiten_git_status` - Показать статус git
- `kaiten_git_push` с параметром `cardId` - Запушить ветку

### Оптимальный workflow

```javascript
// 1. Найти задачи для агента
kaiten_find_cards({ tagName: "agent-safe" })

// 2. Создать ветку для задачи
kaiten_git_branch({ cardId: 12345 })

// 3. Внести изменения и закоммитить
// ...работа над кодом...
kaiten_git_commit({ cardId: 12345, message: "Начал работу" })

// 4. Проверить статус
kaiten_git_status({})

// 5. Запушить
kaiten_git_push({ cardId: 12345 })

Избегай: kaiten_cards без параметров - он загружает все задачи (~3000-6000 байт)


### Пример для других AI

Для Cursor, Copilot или других AI можно использовать те же инструкции - формат совместим.

## Лицензия

MIT

Name		Name	Last commit message	Last commit date
src		src
.env.example		.env.example
.gitignore		.gitignore
.kaiten.config.example		.kaiten.config.example
.kaiten.env.example		.kaiten.env.example
INSTALL.md		INSTALL.md
README.md		README.md
index.js		index.js
mcp-server.js		mcp-server.js
package-lock.json		package-lock.json
package.json		package.json
start-mcp.sh		start-mcp.sh

Команда	Описание
`spaces`	Список пространств
`board [space_id]`	Список досок
`column <board_id>`	Список колонок
`user [query]`	Найти пользователя

Latest commit

History

Folders and files

Repository files navigation

Kaiten MCP

📑 Содержание

Установка

Конфигурация

Настройки проекта (опционально)

Обязательные настройки

Порядок загрузки конфигурации

Использование

Через MCP server (AI assistants)

Команды CLI (для локального использования)

Глобальное использование CLI (опционально)

Использование SDK в проектах

🎯 Оптимизация токенов

Сравнение команд:

Рекомендации для работы с Claude:

Что оптимизировано:

Все доступные команды

Карточки

Карточки

Git интеграция

Подзадачи и комментарии

Метки

Навигация

Файлы

Флаги

Git интеграция (опционально)

Использование SDK в проектах (опционально)

Архитектура

Структура

Конфигурация (приоритет):

Для AI помощников

Настройка MCP server

Для Claude Code (терминал)

Для других AI-ассистентов

Настройка проекта

Важные моменты

Инструкции для AI assistants

Настройка MCP server

🔧 Troubleshooting

MCP инструменты не доступны

Ошибка "No MCP servers configured"

MCP сервер не запускается

Конфигурация не загружается

Альтернатива: Прямое использование SDK

Инструкции для AI

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages