{
  "markdown": "# kaiten-mcp\n\n<!-- mcp-name: io.github.evvfebruary/kaiten-mcp -->\n\n**MCP-сервер для [Kaiten](https://kaiten.ru/)** — интеграция канбан-досок и задач Kaiten с AI-ассистентами ([Cursor](https://cursor.com/), [Claude Code](https://docs.anthropic.com/en/docs/claude-code) и любым MCP-клиентом).\n\nУправляйте карточками прямо из чата: создавайте задачи, перемещайте по колонкам, обновляйте описания, оставляйте комментарии и теги — без ручного копирования из веб-интерфейса и без огромных JSON-ответов API в контексте модели.\n\n## Зачем это нужно\n\n- Подключить **Kaiten к Cursor / Claude Code** через [Model Context Protocol](https://modelcontextprotocol.io/)\n- Работать с пространствами, досками, колонками и карточками голосом агента\n- Экономить токены: ответы компактные по умолчанию (описания — только по запросу)\n- Развернуть локально (stdio) или для команды (Streamable HTTP / Docker / Kubernetes)\n\n## Возможности\n\n- Локальный транспорт **stdio** для Cursor и Claude Code\n- Удалённый **Streamable HTTP** (`POST /mcp`) для командного хостинга\n- Токен Kaiten на каждый запрос (credentials не сохраняются на диске)\n- Компактные списки: страница по умолчанию 20 (макс. 100), без вложений и «шумных» вложенных полей\n- Бенчмарки размера payload (`kaiten-mcp-benchmark`), чтобы ответы не раздувались со временем\n- Структурированные логи в stderr (безопасно для stdio MCP)\n\n## Быстрый старт\n\n### Требования\n\n- Python 3.12+\n- [uv](https://docs.astral.sh/uv/)\n- API-токен Kaiten (Профиль → API-ключ в вашем инстансе, например `https://<компания>.kaiten.ru/profile/api-key`)\n\n### 1. Установка и запуск\n\n```bash\nexport KAITEN_API_TOKEN='ваш-токен'\nexport KAITEN_WORKSPACE_SLUG='ваша-компания'   # → https://ваша-компания.kaiten.ru/api/v1\n\nuvx kaiten-mcp --transport stdio\n```\n\n`uvx` скачивает пакет из PyPI, создаёт изолированное окружение и запускает сервер.\nКлонировать репозиторий не требуется.\n\nДля on-prem / кастомного домена вместо slug задайте полный корень API:\n\n```bash\nexport KAITEN_BASE_URL='https://kaiten.example.com/api/v1'\n```\n\nОстальные переменные — в [`.env.example`](.env.example).\n\n### 2. Cursor\n\nКонфиг проекта уже есть: [`.cursor/mcp.json`](.cursor/mcp.json).\n\n1. Экспортируйте токен и workspace в окружение, которое наследует Cursor:\n\n```bash\nexport KAITEN_API_TOKEN='ваш-токен'\nexport KAITEN_WORKSPACE_SLUG='ваша-компания'\n```\n\n2. Перезапустите Cursor после смены переменных окружения.\n3. Откройте **Output → MCP Logs** и убедитесь, что сервер `kaiten` подключился.\n4. Попросите агента: «покажи пространства» или «найди задачи на доске …».\n\n`${env:KAITEN_API_TOKEN}` и `${env:KAITEN_WORKSPACE_SLUG}` подставляет Cursor. Не коммитьте реальные токены.\n\n### 3. Claude Code\n\nКонфиг проекта: [`.mcp.json`](.mcp.json).\n\n```bash\nexport KAITEN_API_TOKEN='ваш-токен'\nexport KAITEN_WORKSPACE_SLUG='ваша-компания'\nclaude mcp list\n```\n\nИли вручную:\n\n```bash\nclaude mcp add --transport stdio kaiten -- uv run kaiten-mcp --transport stdio\n```\n\n## Примеры запросов к агенту\n\n- «Покажи все пространства в Kaiten»\n- «Найди доски в пространстве X и создай карточку „Исправить баг логина“»\n- «Перенеси задачу #1234 в колонку In Progress»\n- «Добавь комментарий к карточке #1234: готово к ревью»\n- «Повесь тег „hotfix“ на задачу #1234»\n\nТиповой порядок инструментов:\n\n1. `list_spaces` → `list_boards` → `list_columns` / `list_lanes`\n2. `create_task` / `list_tasks` / `get_task` / `update_task` / `move_task`\n3. `add_comment` / `add_tag_to_task` при необходимости\n\n## Инструменты MCP\n\n| Инструмент | Назначение |\n|------------|------------|\n| `list_spaces` | Список пространств (id, title) |\n| `list_boards` | Доски пространства |\n| `list_columns` | Колонки доски |\n| `list_lanes` | Дорожки доски |\n| `create_task` | Создать карточку (`title` + `board_id`) |\n| `get_task` | Детали задачи (`include_description` — по запросу) |\n| `list_tasks` | Фильтрованный компактный список (query, board, column, tag, …) |\n| `update_task` | Обновление полей (title, description, owner, condition, …) |\n| `move_task` | Перемещение (board / column / lane / sort) |\n| `add_comment` / `list_comments` | Комментарии |\n| `list_tags` / `get_task_tags` | Теги |\n| `add_tag_to_task` | Добавить тег **по имени** |\n| `remove_tag_from_task` | Снять тег **по id** |\n\n## Удалённый сервер / Docker / Kubernetes\n\nStreamable HTTP:\n\n```bash\nuv run kaiten-mcp --transport streamable-http --host 0.0.0.0 --port 8000\n```\n\n- Health: `GET /healthz`\n- MCP: `POST /mcp`\n\nDocker:\n\n```bash\ndocker pull ghcr.io/evvfebruary/kaiten-mcp:latest\ndocker run --rm -p 8000:8000 \\\n  -e KAITEN_WORKSPACE_SLUG=ваша-компания \\\n  ghcr.io/evvfebruary/kaiten-mcp:latest\n```\n\nДля локальной разработки образ можно собрать командой `docker build -t kaiten-mcp .`.\n\nКаждый клиент передаёт свой токен:\n\n```http\nAuthorization: Bearer <kaiten-api-token>\n```\n\nПримеры конфигов:\n\n- [`examples/remote-mcp/cursor.mcp.json`](examples/remote-mcp/cursor.mcp.json)\n- [`examples/remote-mcp/claude.mcp.json`](examples/remote-mcp/claude.mcp.json)\n\nЗаметки для Kubernetes:\n\n- Stateless-реплики допустимы (`stateless_http=True`)\n- TLS — на Ingress\n- Увеличьте proxy/read timeouts для streaming\n- Не логируйте заголовок `Authorization`\n- У Kaiten лимит порядка ~50 req/s — делите бюджет между репликами\n\nМодель с Bearer-токеном на запрос — осознанный выбор v1 (не browser OAuth).\n\n## Переменные окружения\n\n| Переменная | Обязательна | Описание |\n|------------|-------------|----------|\n| `KAITEN_API_TOKEN` | Да (stdio) | API-токен; для HTTP — также в `Authorization: Bearer` |\n| `KAITEN_WORKSPACE_SLUG` | Да\\* | Slug: `acme` → `https://acme.kaiten.ru/api/v1` |\n| `KAITEN_BASE_URL` | Да\\* | Полный корень API (on-prem); имеет приоритет над slug |\n| `KAITEN_HOST` / `KAITEN_PORT` | Нет | Bind для HTTP (по умолчанию `127.0.0.1:8000`) |\n| `KAITEN_LOG_LEVEL` | Нет | `DEBUG` \\| `INFO` \\| `WARNING` \\| `ERROR` |\n| `KAITEN_LOG_FORMAT` | Нет | `text` \\| `json` |\n| `KAITEN_LOG_BODIES` | Нет | Компактные redacted-превью в логах |\n| `KAITEN_ENABLE_METRICS` | Нет | Метрики размера payload без секретов |\n\n\\* Нужен **либо** `KAITEN_WORKSPACE_SLUG`, **либо** `KAITEN_BASE_URL`.\n\n## Экономия токенов\n\n- Размер страницы списка по умолчанию: **20** (макс. **100**)\n- В списках нет описаний, вложений и глубоких дублей\n- Мутации возвращают id/url и изменённые поля\n- Обрезка явная: `truncated`, `next_offset`, `has_more`\n- Коротко описанные схемы инструментов\n\nПроверка бюджетов размера ответа:\n\n```bash\nuv run kaiten-mcp-benchmark\nuv run kaiten-mcp-benchmark --check\n```\n\n## Логирование\n\nЛоги всегда идут в **stderr** (совместимо со stdio MCP).\n\n```bash\nexport KAITEN_LOG_LEVEL=INFO\nexport KAITEN_LOG_FORMAT=json\nuv run kaiten-mcp --transport stdio --log-format json\n```\n\nПолезные события: `server_starting`, `tool_start` / `tool_success` / `tool_error`, `kaiten_request`, `kaiten_rate_limited`.\n\nСекреты редактируются; токены видны только как fingerprint вида `token_fp=len=40:…ab12`.\n\n## Разработка\n\n```bash\nuv sync --all-groups\nuv run ruff format .\nuv run ruff check .\nuv run ty check\nuv run pytest\nuv run kaiten-mcp-benchmark --check\n```\n\nLive smoke (опционально, не в CI по умолчанию):\n\n```bash\nKAITEN_API_TOKEN=... KAITEN_WORKSPACE_SLUG=... uv run pytest -m live\n```\n\nПубликация релизов (PyPI, GHCR, Official MCP Registry) описана в [RELEASING.md](RELEASING.md).\n\n## Структура\n\n```text\nsrc/kaiten_mcp/\n  api/           # HTTP-клиент и адаптеры эндпоинтов\n  tools/         # MCP-инструменты\n  auth.py        # Токен на запрос\n  config.py      # Настройки\n  presentation.py\n  metrics.py\n  server.py\n  __main__.py\ntests/\nbenchmarks/\nexamples/remote-mcp/\nserver.json      # Official MCP Registry metadata\nRELEASING.md\n```\n\n## Безопасность\n\n- Токен берётся из HTTP Bearer или `KAITEN_API_TOKEN` на каждый запрос\n- Сервер не пишет токены на диск\n- Предпочитайте переменные окружения, а не хардкод в MCP JSON\n- Права на стороне Kaiten определяются токеном вызывающего\n\n## FAQ\n\n**Как подключить Kaiten к Cursor?**  \nУстановите зависимости через `uv`, задайте `KAITEN_API_TOKEN` и `KAITEN_WORKSPACE_SLUG`, перезапустите Cursor — конфиг уже в [`.cursor/mcp.json`](.cursor/mcp.json).\n\n**Где взять API-токен Kaiten?**  \nВ вашем инстансе: Профиль → API-ключ (`https://<компания>.kaiten.ru/profile/api-key`). OAuth у публичного API Kaiten для этого сценария не используется.\n\n**Чем этот сервер отличается от других kaiten-mcp?**  \nФокус на **компактных ответах** и экономии контекста модели, плюс готовый remote Streamable HTTP для команды без хранения токенов на сервере.\n\n**Можно ли развернуть для всей команды?**  \nДа: Docker / Kubernetes с `streamable-http`; каждый сотрудник передаёт свой Bearer-токен в заголовке.\n\n**Работает ли с on-prem Kaiten?**  \nДа — задайте `KAITEN_BASE_URL` на ваш `/api/v1`.\n\n## Лицензия\n\n[MIT](LICENSE)\n",
  "bytes": 8725,
  "sha": "e21fd33bc07f785175d4e339f2238e81f3511d680ae7ab007815496f5b509765",
  "repo_slug": "evvfebruary/kaiten-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_evvfebruary_kaiten_mcp_fbfed273/readme"
}