# kaiten-mcp

MCP-сервер для [Kaiten](https://kaiten.ru) — предоставляет 246 инструментов для работы с Kaiten API через протокол [Model Context Protocol](https://modelcontextprotocol.io).

Поддерживает два transport-а:
- `stdio` для локального подключения из Claude Code / Claude Desktop
- `HTTP` для удалённого deployment-а в Docker

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

| Область | Модуль | Кол-во |
|---------|--------|--------|
| Карточки | `cards` | 8 |
| Комментарии | `comments` | 4 |
| Участники карточек | `members` | 5 |
| Логи времени | `time_logs` | 4 |
| Теги | `tags` | 6 |
| Чеклисты | `checklists` | 8 |
| Блокировки | `blockers` | 5 |
| Связи карточек | `card_relations` | 9 |
| Внешние ссылки | `external_links` | 4 |
| Файлы карточек | `files` | 4 |
| Подписчики | `subscribers` | 6 |
| Пространства | `spaces` | 5 |
| Доски | `boards` | 5 |
| Колонки и подколонки | `columns` | 8 |
| Дорожки | `lanes` | 4 |
| Типы карточек | `card_types` | 5 |
| Кастомные свойства | `custom_properties` | 10 |
| Документы | `documents` | 10 |
| Вебхуки | `webhooks` | 9 |
| Автоматизации и воркфлоу | `automations` | 11 |
| Проекты и спринты | `projects` | 13 |
| Роли и группы | `roles_and_groups` | 14 |
| Аудит и аналитика | `audit_and_analytics` | 11 |
| Service Desk | `service_desk` | 47 |
| Графики и аналитика | `charts` | 15 |
| Дерево сущностей | `tree` | 2 |
| Утилиты | `utilities` | 14 |
| **Итого** | **27 модулей** | **246** |

## Требования

- Docker **или** Python >= 3.11
- Аккаунт Kaiten с API-токеном

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

| Переменная | Обязательна | Описание |
|------------|-------------|----------|
| `KAITEN_SUBDOMAIN` | Да* | Поддомен компании (`yourcompany` для `yourcompany.kaiten.ru`) |
| `KAITEN_BASE_DOMAIN` | Нет | Базовый домен, по умолчанию `kaiten.ru` |
| `KAITEN_BASE_URL` | Нет | Полный override URL API-хоста; имеет приоритет над `KAITEN_SUBDOMAIN`/`KAITEN_BASE_DOMAIN` |
| `KAITEN_DOMAIN` | Нет | Устаревший fallback для обратной совместимости вместо `KAITEN_SUBDOMAIN` |
| `KAITEN_TOKEN` | Да* | API-токен пользователя Kaiten для локального `stdio` или legacy shared HTTP |
| `MCP_HTTP_HOST` | Нет | Хост для HTTP transport (по умолчанию `0.0.0.0`) |
| `MCP_HTTP_PORT` | Нет | Порт для HTTP transport (по умолчанию `8000`) |
| `MCP_HTTP_BASE_PATH` | Нет | Базовый путь HTTP transport (по умолчанию `/mcp`) |
| `MCP_HTTP_AUTH_MODE` | Нет | `oauth`, `shared` или `none`; для production shared server используйте `oauth` |
| `MCP_PUBLIC_URL` | Да* | Публичный URL MCP endpoint, например `https://mcp.example.com/mcp` |
| `MCP_OAUTH_ISSUER_URL` | Да* | Публичный URL auth/onboarding сервера, например `https://mcp.example.com` |
| `MCP_RESOURCE_METADATA_URL` | Нет | Override URL OAuth protected-resource metadata |
| `MCP_ALLOWED_ORIGINS` | Нет | Comma-separated allowlist browser origins для Streamable HTTP |
| `MCP_REQUIRED_SCOPES` | Нет | OAuth scopes для MCP access token, по умолчанию `kaiten:tools` |
| `MCP_AUTH_TOKEN` | Нет | Legacy shared bearer token для single-tenant HTTP endpoint |

Для локального `stdio` заполняйте `KAITEN_TOKEN` и ровно один способ настройки хоста:
- `KAITEN_SUBDOMAIN` для обычного `*.kaiten.ru`
- `KAITEN_SUBDOMAIN` + `KAITEN_BASE_DOMAIN` для кастомного домена
- `KAITEN_BASE_URL` для полного override

`KAITEN_BASE_URL` нужен для нестандартных доменов и стендов. Примеры:
- `KAITEN_SUBDOMAIN=yourcompany` -> `https://yourcompany.kaiten.ru/api/latest`
- `KAITEN_SUBDOMAIN=kaiten` + `KAITEN_BASE_DOMAIN=kaiten.ru` -> `https://kaiten.kaiten.ru/api/latest`
- `KAITEN_BASE_URL=https://kaiten.kaiten.ru` -> `https://kaiten.kaiten.ru/api/latest`

Для локального запуска через Python сервер читает `.env` через `load_dotenv()`. Переменные процесса имеют приоритет над `.env`.

Быстрый старт с `.env`:

```bash
cp .env.example .env
```

Потом откройте `.env` и оставьте только подходящий вам вариант host-конфига.

Для shared HTTP deployment с `MCP_HTTP_AUTH_MODE=oauth` пользовательский
`KAITEN_TOKEN` не задаётся в `.env`: пользователь вводит свой Kaiten domain и
API key на onboarding-странице, ключ хранится только в памяти до expiry сессии.

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

Ниже описан локальный `stdio` режим. Он сохранён и работает как раньше.

### Способ 1: Docker (рекомендуется)

Собрать образ (однократно):

```bash
docker build -t kaiten-mcp .
```

Эта команда по умолчанию собирает локальный `stdio`-образ. Для удалённого HTTP transport используйте отдельный target `baked-http`.

Зарегистрировать MCP-сервер:

```bash
claude mcp add kaiten \
  -e KAITEN_SUBDOMAIN=yourcompany \
  -e KAITEN_TOKEN=your-api-token \
  -- docker run --rm -i -e KAITEN_SUBDOMAIN -e KAITEN_TOKEN kaiten-mcp
```

Перезапустить Claude Code (`/exit` и запустить заново) — 246 инструментов Kaiten станут доступны.

Для нестандартного домена добавьте `KAITEN_BASE_DOMAIN` или `KAITEN_BASE_URL`:

```bash
claude mcp add kaiten \
  -e KAITEN_SUBDOMAIN=kaiten \
  -e KAITEN_BASE_DOMAIN=kaiten.ru \
  -e KAITEN_TOKEN=your-api-token \
  -- docker run --rm -i \
     -e KAITEN_SUBDOMAIN -e KAITEN_BASE_DOMAIN -e KAITEN_TOKEN kaiten-mcp
```

### Способ 2: Python (venv)

```bash
python3 -m venv .venv
.venv/bin/pip install -e .
claude mcp add kaiten \
  -e KAITEN_SUBDOMAIN=yourcompany \
  -e KAITEN_TOKEN=your-api-token \
  -- .venv/bin/kaiten-mcp
```

Перезапустить Claude Code.

### Способ 3: Docker Compose

```bash
claude mcp add kaiten \
  -e KAITEN_SUBDOMAIN=yourcompany \
  -e KAITEN_TOKEN=your-api-token \
  -- docker compose --project-directory /path/to/kaiten-mcp run --rm -T kaiten-mcp
```

Замените `/path/to/kaiten-mcp` на абсолютный путь к репозиторию.

> **Важно:** Используйте `--project-directory`, а не `-f`. Флаг `-f` задаёт только путь к yml-файлу, но build context и `.env` всё равно ищутся относительно CWD. Флаг `-T` обязателен — без него Docker выделяет pseudo-TTY, что ломает JSON-RPC протокол MCP.

### Проверка

```bash
claude mcp list
```

Сервер `kaiten` должен быть со статусом `connected`.

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

Добавьте в `claude_desktop_config.json`:

**Docker:**

```json
{
  "mcpServers": {
    "kaiten": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "KAITEN_SUBDOMAIN", "-e", "KAITEN_TOKEN", "kaiten-mcp"],
      "env": {
        "KAITEN_SUBDOMAIN": "yourcompany",
        "KAITEN_TOKEN": "your-api-token"
      }
    }
  }
}
```

**Python:**

```json
{
  "mcpServers": {
    "kaiten": {
      "command": "/path/to/kaiten-mcp/.venv/bin/kaiten-mcp",
      "env": {
        "KAITEN_SUBDOMAIN": "yourcompany",
        "KAITEN_TOKEN": "your-api-token"
      }
    }
  }
}
```

## Важные замечания о Docker и MCP

MCP использует stdio transport (JSON-RPC через stdin/stdout). При запуске через Docker:

- Флаг `-i` (`--interactive`) — **обязателен**, держит stdin открытым.
- Флаг `-t` (`--tty`) — **запрещён**, TTY-символы ломают протокол.
- Для `docker compose run` — используйте `-T` (отключает TTY).
- `.env` файл **не нужен** — переменные передаются через `-e` флаги.
- Если используете `KAITEN_BASE_DOMAIN` или `KAITEN_BASE_URL`, их тоже нужно пробросить через `-e`.

Для удалённого deployment-а есть отдельный HTTP transport. Он не требует `-i`/`-T`, потому что работает как обычный web-service.

## Удалённый HTTP deployment

HTTP transport запускается отдельно и не заменяет локальный `stdio`.
Для общего сервера на много пользователей используйте `MCP_HTTP_AUTH_MODE=oauth`.
В этом режиме `Authorization: Bearer ...` — это MCP access token, а не Kaiten API key.
Kaiten API key пользователь вводит на onboarding-странице после OAuth redirect.

Для первого VPS smoke deploy используйте server-side инструкции из
[docs/deployment.md](docs/deployment.md): сервер подтягивает публичную ветку
`remote-server-transport` из GitHub, runtime-переменные лежат вне репозитория,
а сервис временно публикуется напрямую на `http://158.160.37.91:8000` в
`shared` bearer-token режиме. HTTPS/OAuth через Caddy оставлен отдельным
production-шагом.

Для проверки входа именно из ChatGPT используйте HTTPS tunnel из
[docs/deployment.md](docs/deployment.md): ChatGPT Developer mode подключает
remote MCP apps по SSE/streaming HTTP с OAuth/No Auth/Mixed Auth, поэтому
plain HTTP `shared` endpoint на `:8000` нужен только как низкоуровневый smoke.
Для ChatGPT указывайте tunnel URL с trailing slash: `https://.../mcp/`.

### Подключение в ChatGPT

После OAuth-deploy или запуска `deploy/chatgpt-tunnel.sh` сначала проверьте
публичный endpoint:

```bash
curl -sS https://<host>/readyz
curl -sS -o /tmp/kaiten-mcp-unauth.json -w "%{http_code}\n" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"1"}}}' \
  https://<host>/mcp/
```

Ожидаемо: `/readyz` возвращает `{"status":"ready","auth_mode":"oauth"}`,
а unauthenticated `POST /mcp/` возвращает `401 invalid_token`.

В ChatGPT:

1. Удалите или Disconnect старый app/draft, если он был создан при
   `MCP_HTTP_AUTH_MODE=none`.
2. Создайте новый app в Developer mode / Apps settings.
3. Вставьте MCP URL с trailing slash: `https://<host>/mcp/`.
4. Ожидайте в настройках app: `Authorization supported: OAuth`; после
   подключения: `Authorization used: OAuth`.
5. При первом подключении ChatGPT откроет `/authorize`; пользователь вводит
   Kaiten company domain и свой Kaiten API key на странице MCP server.
6. Дальше ChatGPT передаёт только MCP OAuth access token, а MCP server ходит в
   Kaiten с сохранённым request-scoped Kaiten credential.

Если ChatGPT показывает `Authorization supported: None`, app был создан против
no-auth endpoint или endpoint всё ещё отвечает `auth_mode=none`. Удалите этот
draft, проверьте `/readyz`, пересоздайте app после OAuth-deploy.

Если tool возвращает `KAITEN_TOKEN is required`, вызов дошёл до no-auth/legacy
ветки без пользовательской OAuth-сессии. Для публичного ChatGPT deployment-а не
добавляйте `KAITEN_TOKEN` в env контейнера; вместо этого верните
`MCP_HTTP_AUTH_MODE=oauth` и переподключите app.

### Как работает авторизация

1. Администратор публикует один общий MCP server с `MCP_HTTP_AUTH_MODE=oauth`.
2. В production env не задаются `KAITEN_TOKEN` и `MCP_AUTH_TOKEN`: общий сервер не работает от имени одного Kaiten-пользователя.
3. LLM-клиент читает OAuth metadata, регистрирует client через `/register` и отправляет пользователя на `/authorize`.
4. Пользователь вводит Kaiten company domain и свой Kaiten API key на onboarding-странице MCP server.
5. MCP server валидирует ключ запросом к Kaiten `/users/current`, сохраняет Kaiten credential только в памяти и выдаёт authorization code.
6. LLM-клиент меняет code на MCP access token через `/token`.
7. Дальше все tool calls идут с MCP bearer token; MCP server достаёт связанную сессией Kaiten credential и создаёт request-scoped Kaiten client.
8. После expiry сессии или рестарта процесса пользователь должен подключиться заново.

### Способ 1: Docker Compose

```bash
docker compose --profile http --project-directory /path/to/kaiten-mcp up --build -d kaiten-mcp-http
```

Проверка:

```bash
curl http://127.0.0.1:8000/readyz
```

OAuth discovery endpoints:

```text
/.well-known/oauth-protected-resource
/.well-known/oauth-authorization-server
/register
/authorize
/token
```

MCP endpoint по умолчанию публикуется на:

```text
http://127.0.0.1:8000/mcp
```

### Способ 2: Docker run

```bash
docker build --target baked-http -t kaiten-mcp-http:latest .
docker run --rm \
  --read-only --tmpfs /tmp:noexec,nosuid,size=64m \
  --security-opt=no-new-privileges:true --cap-drop=ALL \
  -p 8000:8000 \
  -e MCP_HTTP_AUTH_MODE=oauth \
  -e MCP_PUBLIC_URL=https://mcp.example.com/mcp \
  -e MCP_OAUTH_ISSUER_URL=https://mcp.example.com \
  -e MCP_RESOURCE_METADATA_URL=https://mcp.example.com/.well-known/oauth-protected-resource \
  -e MCP_ALLOWED_ORIGINS=https://claude.ai,https://chatgpt.com \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_PORT=8000 \
  -e MCP_HTTP_BASE_PATH=/mcp \
  kaiten-mcp-http:latest
```

Legacy `MCP_AUTH_TOKEN` режим остаётся для single-tenant/internal запуска:
`MCP_HTTP_AUTH_MODE=shared` + env `KAITEN_TOKEN`. Для общего сервера этот режим
не подходит, потому что все пользователи будут действовать в Kaiten одним токеном.

### Важно для production

- Не публикуйте HTTP endpoint с `MCP_HTTP_AUTH_MODE=none`.
- Не передавайте Kaiten API key как MCP `Authorization` bearer token.
- Ввод Kaiten API key должен происходить только через HTTPS onboarding page.
- Для интернета лучше ставить сервис за Nginx, Caddy, Tailscale или VPN.
- Локальный `stdio` режим для Claude Code и Claude Desktop остаётся предпочтительным, если удалённый deployment не нужен.
- `GET /healthz` проверяет liveness процесса, `GET /readyz` возвращает готовность MCP service и текущий HTTP auth mode.

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

```
src/kaiten_mcp/
  runtime.py             # Общая MCP runtime-логика для stdio и HTTP
  server.py              # MCP-сервер (stdio transport)
  http_server.py         # MCP-сервер (streamable HTTP transport)
  client.py              # HTTP-клиент Kaiten API (httpx, rate limiting)
  tools/
    compact.py           # Компактификация ответов (аватары, лимиты)
    spaces.py            # Пространства
    boards.py            # Доски
    columns.py           # Колонки и подколонки
    lanes.py             # Дорожки (swimlanes)
    cards.py             # Карточки (включая bulk-листинг с авто-пагинацией)
    comments.py          # Комментарии
    members.py           # Участники и пользователи
    time_logs.py         # Логи времени
    tags.py              # Теги
    card_types.py        # Типы карточек
    custom_properties.py # Кастомные свойства
    checklists.py        # Чеклисты и элементы
    blockers.py          # Блокировки карточек
    card_relations.py    # Связи parent/child/planned
    external_links.py    # Внешние ссылки
    files.py             # Файлы карточек (загрузка, скачивание, удаление)
    subscribers.py       # Подписчики карточек
    documents.py         # Документы и группы документов
    webhooks.py          # Вебхуки пространств
    automations.py       # Автоматизации и воркфлоу
    projects.py          # Проекты и спринты
    roles_and_groups.py  # Роли, группы, участники пространств
    audit_and_analytics.py # Аудит, активность, сохранённые фильтры
    service_desk.py      # Service Desk (SLA, пользователи, статистика)
    charts.py            # Графики (CFD, control, cycle/lead time, throughput)
    tree.py              # Навигация по дереву сущностей
    utilities.py         # API-ключи, таймеры, календари, корзина
```

## API-клиент

- Базовый URL:
  - по умолчанию: `https://{subdomain}.kaiten.ru/api/latest`
  - c кастомным base domain: `https://{subdomain}.{base_domain}/api/latest`
  - при `KAITEN_BASE_URL`: override нормализуется до `.../api/latest`
- Авторизация: `Bearer` токен
- Rate limiting: 4.5 запросов/сек (серверный лимит — 5 req/s)
- Автоматический retry при HTTP 429 с exponential backoff (до 3 попыток)

## Тесты

Тесты запускаются **только в Docker**:

```bash
# Все тесты с проверкой 100% покрытия
docker compose -f tests/docker-compose.test.yml up --build test-overseer

# E2E-тесты (нужен .env с KAITEN_SUBDOMAIN/KAITEN_BASE_URL и KAITEN_TOKEN)
docker compose -f tests/docker-compose.test.yml up --build test-e2e-expanded
```

## Лицензия

MIT

## Автор 

Виктор Огнев

## Дисклеймер

Настоящий репозиторий и размещённое в нём программное обеспечение предоставляются по принципу “как есть” (“as is”) и “по мере доступности” (“as available”), без каких-либо гарантий, явных или подразумеваемых. Автор не предоставляет никаких заверений и гарантий в отношении корректности, надёжности, безопасности, пригодности для конкретных целей или отсутствия ошибок в данном решении.

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

Автор настоящего репозитория является единственным разработчиком и правообладателем данного кода. Данное решение разработано и распространяется независимо и не является официальным продуктом или услугой компании Kaiten Software.

Компания Kaiten Software не несёт никакой ответственности за качество работы, производительность, результаты использования или любые последствия, связанные с использованием данного решения. Любые упоминания Kaiten Software приведены исключительно в информационных целях и не означают одобрения, поддержки или аффилированности.