# Kaiten MCP

MCP-сервер для работы с [Kaiten](https://kaiten.ru) через REST API
([developers.kaiten.ru](https://developers.kaiten.ru)). Транспорт — stdio.
Один файл, официальный Python SDK (FastMCP).

## Возможности (22 инструмента)

**Справочники / discovery**
- `kaiten_whoami` — текущий пользователь (проверка токена)
- `kaiten_list_spaces` — пространства
- `kaiten_list_boards` — доски пространства
- `kaiten_get_board` — структура доски (колонки + дорожки)
- `kaiten_list_users` — пользователи (с фильтром)
- `kaiten_list_card_types` — типы карточек

**Карточки**
- `kaiten_search_cards` — поиск с фильтрами (текст, доска, колонка, владелец, состояния, даты, теги…)
- `kaiten_get_card` — карточка целиком
- `kaiten_create_card` — создать
- `kaiten_update_card` — обновить поля
- `kaiten_move_card` — переместить (колонка/дорожка/доска)
- `kaiten_archive_card` — архив / восстановление
- `kaiten_delete_card` — удалить (безвозвратно)

**Прочее на карточке**
- `kaiten_list_comments`, `kaiten_add_comment`
- `kaiten_add_checklist`, `kaiten_add_checklist_item`, `kaiten_update_checklist_item`
- `kaiten_add_member`, `kaiten_remove_member`
- `kaiten_add_tag`
- `kaiten_add_time_log` (время в минутах)

Поиск и списки возвращают компактные сводки (экономия контекста); полные данные — через `kaiten_get_card`. Лимит запросов Kaiten (50 rps, код 429) обрабатывается с авто-повтором по заголовку `X-RateLimit-Reset`.

## Установка

```bash
pip install -r requirements.txt
# или: pip install "mcp>=1.2.0" httpx
```

Токен: профиль → `https://<домен>.kaiten.ru/profile/api-key`.

## Запуск / проверка

```bash
KAITEN_DOMAIN=mycompany KAITEN_API_TOKEN=xxxx python kaiten_mcp.py
```

Через MCP Inspector:

```bash
KAITEN_DOMAIN=mycompany KAITEN_API_TOKEN=xxxx \
  npx @modelcontextprotocol/inspector python kaiten_mcp.py
```

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

```bash
claude mcp add kaiten \
  --env KAITEN_DOMAIN=mycompany \
  --env KAITEN_API_TOKEN=xxxx \
  -- python /полный/путь/к/kaiten_mcp.py
```

## Подключение к Claude Desktop

`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "kaiten": {
      "command": "python",
      "args": ["/полный/путь/к/kaiten_mcp.py"],
      "env": {
        "KAITEN_DOMAIN": "mycompany",
        "KAITEN_API_TOKEN": "xxxx"
      }
    }
  }
}
```

## Переменные окружения

| Переменная | Назначение |
|---|---|
| `KAITEN_DOMAIN` | поддомен (для `mycompany.kaiten.ru` → `mycompany`) |
| `KAITEN_BASE_URL` | альтернатива: полный URL `https://mycompany.kaiten.ru/api/v1` |
| `KAITEN_API_TOKEN` | bearer-токен (обязательно) |
| `KAITEN_API_VERSION` | `v1` (по умолчанию) или `latest` |
| `KAITEN_TIMEOUT` | таймаут запроса, сек (по умолчанию 30) |

## Типичный сценарий

1. `kaiten_list_spaces` → выбрать пространство
2. `kaiten_list_boards` → выбрать доску
3. `kaiten_get_board` → узнать `column_id` / `lane_id`
4. `kaiten_create_card` / `kaiten_search_cards` / `kaiten_move_card`

## Лицензия

[MIT](LICENSE) © 2026 Denis Zakharov