Миграция документации через MCP-сервер: опыт переезда GitBook на Diplodoc за четыре дня

# Миграция документации через MCP-сервер: опыт переезда GitBook на Diplodoc за четыре дня

В условиях нестабильности инфраструктуры документационного портала, команда разработчиков вынуждена была принять жесткое решение: перенести контент на платформу Diplodoc. Задача оказалась решена нестандартным способом — без написания скриптов конвертации, с использованием возможности прямого доступа агента ИИ к данным источника через новый открытый стандарт.

Кризис доступности и выбор инструмента

Проблема началась не с кода документации, а с общей архитектуры. Глобальный переход на PostgreSQL обнажил скрытые баги в инфраструктуре GitBook, из-за чего доступ к справочной системе стал intermittent (прерывистым). Для продукта, зависящего от поддержки пользователей, это стало сигналом тревоги. Ожидание «само рассосется» затянулось на два месяца, превратившись из стратегии минимизации рисков в операционный тупик.

Команда рассматривала несколько путей выхода:

* Разработка собственного движка: Отбрасывалась как излишне затратная задача для временного решения, требующая поддержки собственной инфраструктуры. * Перенос на Tilda: Контрапункт к требованиям «документации как кода». Перенос сотен страниц в визуальном редакторе требовал бы значительных временных затрат и лишил бы возможность управлять контентом через Git. * Другие зарубежные SaaS-решения: Оставался за скобками из-за рисков зависимости от иностранного облака. * Diplodoc: Решение нашлось случайно. Дизайнер, изучая визуальные решения Yandex AI Studio, обратил внимание на структуру документации и нашел под капотом проект Diplodoc. Инструмент показался идеальным сочетанием качества интерфейса и открытости кода.

Ключевые аргументы в пользу выбора Diplodoc: * Документация как код: Контент хранится в Markdown в репозитории GitHub, что позволяет использовать рабочий процесс ревью через Pull Requests. * Открытый исходный код: Наличие 50+ репозиториев на GitHub дает возможность аудита безопасности и прозрачности. * YFM (Yandex Flavored Markdown): Поддержка расширенных блоков кода и схем, необходимых для технической документации. * Стабильность: Контроль над инфраструктурой и отсутствие непредсказуемых простоев чужого сервиса.

Технология миграции: как MCP заменил скрипты

Основной технический интерес представляет способ переноса контента. Традиционный подход предполагает выгрузку всех файлов из одного хранилища, их обработку скриптами конвертации и загрузку в новое. В данном случае этот путь был обойден.

Было использовано взаимодействие через MCP (Model Context Protocol). Это открытый стандарт, позволяющий LLM-моделям получать доступ к внешним системам через программные интерфейсы, а не просто анализировать статические файлы.

Порядок действий был следующим: 1. Настройка доступа: К адресу портала GitBook был добавлен путь /~gitbook/mcp. Это подняло нативный сервер управления контекстом. 2. Подключение агента: Модель Claude была подключена к этому серверу. 3. Автономная работа: Агент самостоятельно прошел по структуре документации, прочитал содержимое страниц и конвертировал их в формат YFM, совместимый с Diplodoc.

Этот подход позволил обойти проблему лимитов контекстного окна. Агент не был вынужден разбивать большой объем текста на фрагменты, так как MCP-сервер предоставлял доступ к контенту напрямую.

Где проходит граница возможностей агента

Использование ИИ-агента для генерации контента не означает полную автоматизацию. Граница между «сделал модель» и «сделано для пользователя» лежит в плоскости визуализации.

* Уровень разметки (Git): Агент идеально справился с логикой. Ветка в репозитории содержала валидный Markdown, диф-патчи были чистыми, сборка проходила успешно. * Уровень рендеринга (Браузер): Здесь начинались проблемы. Разная интерпретация расширений YFM приводила к тому, что блоки разъезжались, списки сливались с абзацами, а таблицы теряли структуру. Эти визуальные несоответствия невозможно выявить только путем анализа кода.

Работа стала циклической: человек визуализировал страницу, находил несоответствие и давал краткую корректировку агенту. Этот метод «увидел — сказал — исправил» оказался более эффективным, чем постановка абстрактных задач.

Десять вещей, которые пришлось делать руками

Переход с SaaS на собственную сборку документации (docs-as-code) возвращает разработчикам все ответственности, которые ранее были скрыты за настройками сервиса. Вот десять технических нюансов, с которыми пришлось столкнуться после конвертации контента:

1. Пустая страница для роботов: По умолчанию текст отрисовывается в браузере пользователя, но роботам поисковых систем виден только пустой HTML-контейнер. Статический рендер нужно включить явно. 2. Отсутствие служебных файлов: В отличие от GitBook, здесь необходимо самостоятельно создать и поддерживать robots.txt, sitemap.xml и тег canonical для корректной индексации. 3. Дубликаты страниц: У каждого URL существует две версии — с квантификатором и без. Без canonical поисковики могут индексировать дубли. 4. Управление редиректами: Необходимо решить судьбу старых ссылок. В данном случае старый портал оставлен активным, что позволило не настраивать сложные карты 301-редиректов сразу. 5. Некорректные редиректы платформы: Некоторые внутренние переходы работали через meta refresh, что браузеру казалось редиректом, а поисковикам — обычной страницей. Это нарушает правила для sitemap. 6. Мертвые ссылки: Абсолютные ссылки, ведущие на старый домен, сборка пропускает, так как не видит ошибок. Их приходится искать и проверять отдельным прогоном. 7. Отсутствие в оглавлении: Страница может физически существовать в репозитории, но не собираться для сайта, если она не включена в навигационную структуру. 8. Ошибки 404: По умолчанию ошибка может вести на главную страницу с кодом 200, что для поисковиков означает «страница существует, но контент не найден». Нужна настоящая страница 404. 9. Проблемы локального поиска: Русский языковой пакет поисковика может считать слова вроде «день», «время» или «имя» стоп-словами, что приводит к некорректным результатам поиска в документации CRM. 10. Качество экспорта: Источниковый материал после миграции требует очистки. Дубликаты текста, случайные имена файлов для изображений и «мертвые» медиа-элементы часто остаются без внимания при автоматическом переносе.

Итог и выводы

Полный цикл миграции — от принятия решения до деплоя новой версии документации — занял четыре дня. Каждая фаза работала четко по графику. Однако важно понимать: технический переезд не означал конец работы над документацией. Портал остается «живым» объектом, требующим постоянной поддержки актуальности контента.

Главный урок проекта заключается в том, что отказ от зависимости от «магических» функций облачного SaaS возвращает команде полный контроль, но и полную ответственность за инфраструктуру поиска, редиректов и рендеринга. Использование MCP-серверов позволяет значительно ускорить технические операции по миграции, но человеческий фактор остается критически важным для гарантии качества пользовательского опыта.

*«Проблема была не в том, что портал не открывался, а в том, что мы не могли ни предсказать, откроется ли он завтра, ни повлиять на это. Доступность твоей документации перестаёт быть твоим решением.»* — это наблюдение стало главным мотиватором для перехода на контролируемую инфраструктуру.