Решение проблем

Начните со статуса сервера и stderr в MCP-клиенте. Pino пишет диагностику в stderr отдельными JSON-строками, уровень по умолчанию — info. Stdout содержит только сообщения MCP. Ошибки запуска и инструментов исключают учётные данные и исходные тела ответов Kaiten.

Клиент не может запустить сервер

1. Выполните node --version и убедитесь, что установлена версия 24 или новее. Node.js, npm и npx должны быть доступны в PATH вашего MCP-клиента.
2. Сверьте аргументы запуска с руководством подключения. Добавьте --yes, чтобы отключить запрос подтверждения установки. При первом запуске npm нужен доступ к настроенному registry для загрузки пакета и зависимостей.
3. Проверьте передачу KAITEN_ORIGIN и KAITEN_TOKEN процессу сервера. Переменные из другого терминала могут отсутствовать у приложения.
4. Используйте origin вида https://company.kaiten.ru без /api/v1, встроенных учётных данных, query и fragment.
5. Удалите некорректный KAITEN_TIMEOUT_MS или задайте целое от 1 до 2147483647. Пустая строка недопустима.

При некорректной настройке процесс завершается с кодом 1 и безопасным сообщением с именами этих переменных. После исправления перезагрузите конфигурацию клиента.

Процесс бездействует в терминале

Сервер ожидает сообщения MCP на stdin. Он не открывает порт и не выводит баннер запуска в stdout. Запустите его через MCP-клиент и проверьте обнаружение инструментов. Процесс завершается при закрытии stdin, по SIGINT или SIGTERM; завершение также отменяет ожидающие HTTP-запросы.

Подключение работает, но инструмент возвращает ошибку

Ошибки операций содержат isError: true и JSON-текст в content, например:

{
  "code": "KAITEN_HTTP_ERROR",
  "message": "Kaiten returned HTTP 403.",
  "status": 403
}

Код	Значение	Следующее действие
KAITEN_HTTP_ERROR	Kaiten вернул ошибочный HTTP-статус	Проверьте статус, права токена и ID ресурсов
INVALID_KAITEN_RESPONSE	Некорректный JSON или ответ, несовместимый со схемой клиента или сервера	Запишите имя инструмента и версии пакетов; опишите воспроизводимый случай без учётных данных
NETWORK_ERROR	Fetch не смог связаться с Kaiten	Проверьте origin и доступ к сети из окружения сервера
TIMEOUT	Операция превысила KAITEN_TIMEOUT_MS	Проверьте доступность Kaiten; прочитайте изменяемый ресурс перед повторной записью
CANCELLED	Отмена или завершение сервера прервало операцию	При необходимости переподключитесь; прочитайте ресурс перед повторной записью
INTERNAL_ERROR	Возникла неклассифицированная ошибка	Запишите инструмент, версию пакета и безопасное сообщение для issue

Для HTTP-ошибок полезны следующие проверки:

• 401/403: проверьте токен и доступ к нужному пространству или карточке.
• 404: заново найдите ID ресурса и проверьте доступ с тем же токеном.
• 400: проверьте значения, целевое расположение и типы пользовательских полей.
• 429/5xx: перед повтором проверьте доступность сервиса или ограничение запросов.

Это рекомендации для диагностики; сервер сообщает статус и исключает исходное тело ошибки Kaiten. Автоматических повторов нет. Неудачная или отменённая запись могла уже дойти до Kaiten.

Аргументы отклонены до отправки запроса

Используйте схему из MCP tools/list и справочник. Неизвестные аргументы запрещены, ID должны быть положительными безопасными целыми числами, а ID и флаги — числами и булевыми значениями JSON. Объект changes должен содержать хотя бы одно изменение. Для дат используйте YYYY-MM-DD или ISO timestamp с часовым поясом.

Для изменения роли member_id — ID связи из kaiten_list_card_members; type принимает только 2. Для свойств ключи имеют вид id_7, а объект в kaiten_set_card_properties должен содержать хотя бы одну запись.

Результаты поиска неполные или курсор отклонён

Следуйте next_cursor до null, сохраняя фильтры. Для других списков используйте next_offset. Пропущенные фильтры сохраняют значения по умолчанию Kaiten; для живых карточек явно задайте archived: false. Полное описание читайте через kaiten_get_card.

Поиск использует API v1 и курсоры offset:N. Старые курсоры OpenSearch несовместимы: начните поиск без cursor. Локальная пагинация заново получает список при каждом вызове и не хранит снимок. См. пример продолжения поиска.

Сообщить о проблеме

Укажите версию пакета, версию Node.js, название MCP-клиента, инструмент и безопасную ошибку в GitHub issue. Укажите фиксированную версию пакета, если она задана в аргументах npx или npm exec. Удалите токены и закрытые данные компании из логов и примеров аргументов.