Я перестал показывать ИИ файлы и дал ему сам MODX

С искусственным интеллектом в веб-разработке мы работаем уже достаточно давно. На проектах с MODX 2 ChatGPT помогал искать ошибки, разбирать чужой код, писать сниппеты и компоненты, переделывать шаблоны. Польза была вполне практической, но сам процесс, в большей части, оставался традиционным. Нужно было найти нужный чанк, принести его в чат, объяснить, откуда берутся данные, показать TV-поля, получить исправленный код, вернуть его в MODX и проверить результат.

ИИ заметно ускорял написание кода, но разработчик при этом продолжал работать «курьером» между ИИ и сайтом. В какой-то момент мне захотелось убрать именно эту часть работы. Не дать ChatGPT полный SSH-доступ и посмотреть, что он там натворит, а сделать так, чтобы он сам видел структуру сайта примерно так же, как её видит разработчик MODX, ресурсы как ресурсы, чанки как чанки, TV как TV, а не просто как строки в таблицах базы данных.

Так из довольно простого желания перестать делать Ctrl+C, Ctrl+V между окнами родился эксперимент, который постепенно вырос в отдельный проект. И в рабочий инструмент.

MODX 3 подкрался незаметно…

Повод получился достаточно комичный. Один новый разработчик, который ещё не успел выучить наши внутренние стандарты, какого-то чёрта поставил на новый проект MODX 3. Раньше третью ветку мы сознательно обходили. В первую очередь нам мешал MIGX, который используется достаточно активно, особенно на старых проектах. С совместимостью долгое время были проблемы, поэтому особого желания переводить накопившееся хозяйство на MODX 3 у нас не возникало.

Но на момент написания статьи «тройка» уже заметно повзрослела, большинство детских болезней прошло, ситуация с дополнениями стала значительно лучше, и откатывать новый сайт обратно на MODX 2 только потому, что «мы так привыкли», показалось уже не очень разумным. Тем более что сайт, зараза, работал.

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

Пошёл смотреть GitHub, а что ж еще...

Open source в нормальном смысле этого слова

Проектов нашлось немного. На момент, когда мы выбирали основу, ближе всего к нашей задаче оказался modxMCP от dampilov94.

Это был уже далеко не пример из трёх команд. Проект умел работать с ресурсами, шаблонами, чанками, сниппетами, TV, настройками и дополнительными компонентами, искать код и места использования элементов. В нём уже были project_overview, который позволяет быстро получить компактную карту проекта, и dependency_graph, который строит связи между элементами MODX, находит битые ссылки и помогает понять, что именно может затронуть изменение.

Параллельно посмотрели modxmcp от karamble. Он решал похожую задачу немного иначе. Проект ориентирован на MODX 3 и делает заметный упор на штатный путь изменения данных через процессоры MODX. Мне понравились более компактная внутренняя организация и довольно строгий подход к тому, какими правами вообще должен обладать агент.

Если очень грубо свести то, что было важно именно нам, картина получалась примерно такая.

Выбирать здесь «лучший MCP» я не стал. У проектов разные сильные стороны, поэтому мы взяли то, что лучше подходило нашей задаче, а дальше начали собирать собственную архитектуру. На то он, собственно, и open source.

Почему просто SSH здесь недостаточно

SSH у агента тоже есть, и он нужен, потому что если надо разобраться со сборкой Bootstrap, посмотреть конфигурацию сервера или изменить SCSS, предметный MCP для MODX ничем не поможет. Но когда задача относится к самой CMS, одного доступа к файлам уже мало. Сайт на MODX это не каталог PHP-файлов. Значительная часть его структуры находится в ресурсах, шаблонах, чанках, сниппетах, TV, системных настройках и связях между ними. Можно дать агенту ещё SQL, информации станет больше, но таблицы базы данных всё равно плохо объясняют смысл этой информации.

Для человека modChunk это не просто запись с полем content. Разработчик понимает, что этот чанк может использоваться несколькими шаблонами и сниппетами, а изменение общей карточки товара способно затронуть половину каталога. Вот этот смысл хотелось сохранить и для агента, чтобы он видел не просто данные, которые можно изменить, а объект CMS со связями и последствиями.

Позже мы сформулировали эту мысль в документации проекта достаточно коротко.

MODX MCP не пытается дать ИИ максимальный доступ к сайту. Он пытается дать ИИ правильный доступ.

Для меня это до сих пор главная идея всей конструкции.

Первый тест был максимально «научным»

После адаптации компонента под MODX 3 надо было проверить самую простую вещь, агент действительно способен получить задачу и довести её до изменения работающего сайта. Поэтому я попросил сделать фон сайта красным и увеличить размер H1. В два раза. Содержательность задачи примерно нулевая, зато результат сложно не заметить. На проекте использовался Bootstrap, агент сам нашёл исходники стилей, внёс изменение, пересобрал CSS и показал результат. После этого я попросил всё вернуть обратно, и сайт вернулся в исходное состояние.

Никакого технологического шока не произошло, с подобными системами мы уже работали и понимали, что такая цепочка в принципе возможна. Интереснее было другое, мне не пришлось заранее объяснять, какой файл открыть, где искать нужное значение и какой командой пересобирать стили. Я поставил задачу на уровне результата, а технический путь агент нашёл самостоятельно.

На красном фоне эта разница выглядит почти игрушечной, но из неё довольно быстро вырос вполне рабочий подход. Первое, что теперь делает агент при подключении нового сайта, это разбирает его структуру, получает ресурсы, шаблоны, чанки, сниппеты и TV, смотрит взаимосвязи между элементами, установленные компоненты, фронтенд-стек и другие устойчивые особенности проекта. Результат такой инвентаризации фиксируется в проектном AGENTS.md, поэтому в следующем чате не приходится снова начинать знакомство с сайтом с нуля.

И вот после этого у нас начались проблемы...

Дать агенту MODX оказалось проще, чем научить его думать как MODX-разработчик

Одна из первых реальных задач была совершенно обычной. Есть раздел сайта, нужно вывести дочерние ресурсы через pdoResources, использовать определённые TV и собрать карточки. Задачу сформулировали достаточно точно, агент внимательно всё прочитал и сделал статическую вёрстку. Внешне результат был правильный, пять карточек стояли на месте, данные выглядели нормально, страница работала, только решение не имело почти никакого отношения к архитектуре сайта. Оказалось, что доступ к сущностям MODX ещё не означает понимания нормальных способов работы с MODX. Можно дать модели 180 инструментов, но это совершенно не гарантирует, что она выберет правильный.

В исходном modxMCP эта проблема уже частично учитывалась. В документации был рекомендуемый порядок работы, сначала сориентироваться в проекте, затем найти нужный объект, посмотреть его окружение и зависимости, перед изменением оценить последствия, для опасной операции сначала выполнить предварительную проверку, после записи проверить результат. Мы пошли дальше в ту же сторону и добавили правила конкретного проекта и накопленные знания о его архитектуре. Задача постепенно сместилась от желания дать модели побольше команд к попытке научить её выбирать, какая из этих команд вообще уместна.

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

Порт под MODX 3 довольно быстро перестал быть просто портом

Исходный modxMCP был рассчитан на MODX 2, а первый наш проект работал на третьей версии. Первым этапом была вполне понятная задача, адаптировать компонент под MODX 3. Подробно пересказывать изменения пространств имён, процессоров и другие отличия двух поколений MODX смысла не вижу, любой, кто переносил дополнение со второй версии на третью, примерно представляет объём веселья.

Пока версия для MODX 3 была небольшим ответвлением, отдельная кодовая база выглядела терпимо. Потом в неё стали добавляться свои проверки, изменения клиента, установщика, безопасность и новые инструменты. К этому моменту первоначальный эксперимент уже превратился в рабочий проект, и захотелось использовать новые возможности на старых сайтах с MODX 2. Поддерживать две почти одинаковые кодовые базы и синхронно переносить между ними каждое изменение выглядело уже не разработкой, а добровольным мазохизмом.

Архитектуру пришлось переделывать ещё раз. Большой общий обработчик начали разбивать на отдельные классы и модули, появился реестр инструментов, общая среда выполнения и отдельный платформенный слой, который скрывает различия между MODX 2 и MODX 3.

Прикладной инструмент теперь не должен сам решать, какой конкретный класс существует в MODX 2, а какой в MODX 3. Он работает с логической сущностью, а различия остаются на границе платформы. Интерфейс этого слоя получился небольшим.

interface PlatformInterface
{    
    public function key();
    public function majorVersion();
    public function supports($modx);
    public function className($logicalName);
    public function processorTarget($processor);
    public function runProcessor(
        $modx,
        $processor,
        array $properties = array(),
        array $options = array()
    );
}

Например, инструменту нужен resource. Для MODX 2 адаптер подставит modResource, для MODX 3 соответствующий класс Revolution. Та же логика работает с чанками, шаблонами, TV и процессорами MODX. Код здесь совершенно нереволюционный, ценность в том, что различия двух платформ перестают расползаться по всей системе в виде десятков проверок версии. Если завтра меняется способ запуска процессора на одной платформе, исправление остаётся в одном месте. Именно эту часть архитектуры мы уже заметно развивали сами, опираясь на опыт обоих изученных открытых проектов.

Иногда важнее не что изменить, а каким путём

Предметный интерфейс позволяет решить ещё одну проблему, которая плохо заметна при прямой работе с базой. Запись в MODX не всегда равна корректному изменению MODX.

В истории исходного modxMCP был хороший реальный пример. Операции построчного редактирования и массовой замены когда-то сохраняли содержимое напрямую. Результат в MODX был правильный, сайт работал, но VersionX не создавал новую версию, потому что изменение обходило стандартные события сохранения. Потом эти операции переделали так, чтобы итоговое сохранение проходило через штатный процессор MODX.

Этот пример мне нравится больше длинных рассуждений о правильной архитектуре. Данные изменились, пользователь увидел нужный результат, но система целиком получила изменение не тем путём.

В нашей модульной архитектуре изменяющий инструмент в итоге вызывает платформенный слой примерно так.

$response = $context->platform()->runProcessor(
    $context->modx(),
    $this->spec['processor'],
    $props
);

Какой конкретно процессор стоит за логической операцией в MODX 2 или MODX 3, решает адаптер, инструменту это знать не требуется. В итоге изменение проходит тем способом, который понимает сама CMS, с её событиями, процессорами и поведением установленных компонентов. Именно здесь предметный MCP становится чем-то большим, чем удобный набор удалённых команд.

Что получилось на сегодняшний день

Текущая общая ветка называется MODX MCP и опубликована под лицензией MIT. Из одного дерева исходников собираются версии для MODX Revolution 2.8.x и 3.x, MCP-клиент и публичный набор действий остаются общими, различия платформ вынесены в адаптеры.

На момент подготовки статьи все 182 зарегистрированных действия переведены на модульную среду выполнения. MODX 3 уже прошёл проверку на боевом сайте. Для MODX 2 основные сценарии сначала прогнали на тестовой установке, сейчас компонент подключён уже к нескольким продакшенам. Дальше там неизбежно будут вылезать те пограничные случаи, которые никакой тестовый стенд заранее не показывает. Но мы к этому готовы.

Сам компонент я оставил открытым. Это кажется честным хотя бы потому, что проект вырос из чужого open source, а значительная часть универсальной работы полезна не только нашей инфраструктуре. Над компонентом продолжается активная работа, он развивается вместе с реальными задачами и новыми сайтами.

Сейчас готовим компонент к публикации в официальном каталоге MODX Extras и на modstore.pro. Планируем разместить его там в ближайшее время, чтобы пакет можно было получать привычным для разработчиков MODX способом.

При этом MODX MCP это именно предметный интерфейс к CMS, а не вся система целиком. В рабочем контуре рядом остаются SSH, браузер, файловые инструменты и закрытая серверная часть. Если проблема находится в SCSS, конфигурации веб-сервера или PHP-файле, нет никакого смысла изображать, что MCP должен решить всё на свете.

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

Что я из этого вынес

Начиналось всё с желания перестать таскать руками код между MODX и ChatGPT. В процессе выяснилось, что дать агенту технический доступ к сайту довольно просто. Гораздо интереснее решить, какую картину сайта он при этом видит.

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

MODX здесь только конкретный пример. В WordPress сущности будут называться по-другому, в CRM или собственной системе тоже, но принцип остаётся тем же. Чем сложнее система, тем полезнее дать агенту интерфейс, который сохраняет смысл самой системы, а не только низкоуровневый доступ к её данным.

На первом боевом тесте мы всего лишь сделали фон красным и увеличили заголовок. Через некоторое время из этого выросла общая архитектура для двух поколений MODX и рабочий инструмент. Вместе с ним появился следующий вопрос, что вообще можно разрешать агенту менять самостоятельно и как сделать эти изменения контролируемыми и обратимыми.

Во второй части (а их планируется три) расскажу о блокировках, резервных копиях, откате, уровнях риска и о том, что пришлось построить вокруг MCP, прежде чем я решился спокойно сказать агенту «исправляй».

Если эта публикация вас вдохновила и вы хотите поддержать автора — не стесняйтесь нажать на кнопку