Разработка

Проект — TypeScript ESM-сервер для Node.js 24+. Все запросы Kaiten проходят через @2chevskii/kaiten-client, закреплённый на версии 1.0.3 из публичного npm. Документация — приватный npm workspace с VitePress 2.0.0-alpha.20.

Сборка из исходников

Из корня репозитория:

npm ci
npm run build
npm run check

npm ci устанавливает зависимости сервера и документации по зафиксированному lockfile. Сборка создаёт bin/cli.js. Для запуска исходников из корня репозитория используйте node bin/cli.js с необходимыми переменными окружения Kaiten. Генерируемые файлы исключены из Git и не редактируются вручную.

Команда	Назначение
npm run build	Компиляция src/ в bin/
npm run build:watch	Пересборка при изменении исходников сервера
npm run test:types	Проверка типов исходников и тестов
npm test	Протокольные тесты; сначала выполните сборку
npm run lint	Проверка ESLint
npm run format:check	Проверка форматирования Prettier
npm run docs:dev	Локальный предпросмотр документации
npm run docs:build	Сборка документации на двух языках
npm run check	Сборка, типы тестов, тесты, lint, форматирование и документация

npm start запускает собранный CLI для разработки. Для опубликованного пакета используйте настройку npx или npm exec.

Путь запроса и карта проекта

MCP-клиент запускает src/cli.ts. CLI читает настройки, создаёт Kaiten-клиент и MCP-сервер и обслуживает stdio. Регистрация инструментов задаёт строгие входные схемы и выходные проекции. Каждый инструмент вызывает реальную библиотеку Kaiten; реестр проверяет результат и возвращает структурированный JSON с эквивалентным текстом.

Путь	Ответственность
src/cli.ts	Stdio, обработка ошибок запуска и завершение
src/config.ts	Переменные окружения и проверка тайм-аута
src/server.ts	Создание Kaiten-клиента и сервера, регистрация групп инструментов
src/tool-registry.ts	MCP-аннотации, тайм-аут и отмена, проверка ответа и обработка ошибок
src/schemas.ts	Общие ID, даты, пагинация и проверка изменений
src/views.ts	Публичные проекции ответа; неизвестные upstream-поля удаляются
src/results.ts	Обёртки сущностей и страниц
src/errors.ts, src/logger.ts	Безопасные ошибки операций и JSON-диагностика в stderr
src/tools/	Навигация, чтение и запись карточек, комментарии, связи, чек-листы и поля
test/harness.ts, test/tool-cases.ts	Локальный HTTP-сервер, реальное MCP-подключение через stdio и контракты инструментов
tools/	Расчёт preview-версий и проверка установленного пакета
docs/, docs/ru/	Английские и русские страницы с одинаковыми маршрутами
docs/.vitepress/config.ts	Навигация языков, боковое меню и локальный поиск
.github/workflows/	CI, публикация пакетов, релизы и Pages

Сигнал отмены инструмента объединяет отмену клиентом, завершение процесса и тайм-аут операции. Тайм-аут охватывает всю операцию инструмента. Автоматических повторов нет. Pino синхронно пишет диагностику запуска и транспорта в stderr.

Изменение инструмента

1. Измените соответствующий модуль в src/tools/, используя публичный API Kaiten-клиента.
2. Задайте строгие входные схемы и явные проекции ответа. Сохраните различия между пропущенными полями, null, false и 0.
3. Дополните HTTP-контракты и тесты поведения ответами реальной формы, включая отсутствующие поля и null.
4. Обновите публичное поведение на двух языках и выполните npm run check.

Используйте относительные .ts-импорты, kebab-case имена файлов, строгий TypeScript и форматирование ESLint/Prettier. Разделяйте транспорт, регистрацию, маппинг и представление. Правила репозитория находятся в корневом AGENTS.md.

Что подтверждают проверки

Протокольные тесты запускают собранный CLI из другого рабочего каталога и подключают официальный MCP-клиент. Вызовы проходят через установленную библиотеку Kaiten к локальному HTTP-серверу. Набор покрывает все 44 контракта, сценарий карточки с сохранением состояния, пагинацию, валидацию, nullable-поля, безопасные ошибки, отмену и завершение.

Проверки подтверждают MCP- и HTTP-контракты на тестовых ответах. Они не обращаются к реальной компании Kaiten и не подтверждают интеграцию с конкретным MCP-приложением. Для реального чтения выполните проверку подключения.

Изменение документации

Запустите npm run docs:dev и откройте URL из вывода VitePress. Проверьте оба языка, переключение языка, локальный поиск и навигацию. Сохраняйте одинаковые имена страниц в docs/ и docs/ru/, чтобы переключение вело к соответствующей странице. При добавлении страницы обновляйте оба боковых меню.

Локально VITEPRESS_BASE равен /. Workflow Pages задаёт /kaiten-mcp/. Ссылки должны работать с этим base; сборка пишет в docs/.vitepress/dist/ и проверяет внутренние ссылки на страницы.

Доставка изменений и проверка пакета

Используйте отдельную ветку и небольшие Conventional Commits. Отправьте ветку, откройте PR и проверьте hosted CI. CI также устанавливает созданный архив во временный каталог, проверяет метаданные пакета, инициализацию MCP и tools/list. Проверка пакета не использует реальные учётные данные и не вызывает API Kaiten.

Каналы пакетов, настройка registry и порядок стабильного релиза описаны в CI/CD и релизах.