MODX2MCP

MODX2MCP — компонент для подключения внешних ИИ-агентов к MODX Revolution 2.8.x через протокол Model Context Protocol.

Важно: MODX2MCP не является готовым ИИ-агентом и не добавляет искусственный интеллект в MODX сам по себе.

После установки компонента в панели управления не появится чат, которому можно сразу поручать работу с сайтом. Компонент решает другую задачу: он создаёт специальный интерфейс между MODX и внешней агентной системой.

То есть MODX2MCP — это одна из частей более крупного контура:

Пользователь → ИИ-агент → MODX2MCP → MODX

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

Такая архитектура позволяет не встраивать конкретный ИИ-сервис непосредственно в MODX и не привязывать компонент к одной модели, одному чату или одному способу управления.

Что делает MODX2MCP

MODX2MCP предоставляет внешнему агенту специализированный набор инструментов для работы с MODX.

Вместо произвольного доступа к базе данных или файловой системе агент получает возможность работать непосредственно с сущностями CMS:

• ресурсами и структурой сайта;
• шаблонами;
• чанками;
• сниппетами;
• плагинами;
• TV-полями и их значениями;
• системными настройками;
• категориями;
• контекстами;
• пользователями и группами;
• политиками доступа и шаблонами политик;
• группами ресурсов и их составом;
• источниками файлов и медиа;
• пакетами и установленными дополнениями;
• наборами свойств;
• настройками ClientConfig;
• MIGX;
• miniShop2;
• VersionX;
• VirtualPage.

В текущей версии доступно 192 публичных инструмента MCP: 81 операция чтения и 111 изменяющих операций.

Панель управления MODX2MCP

В состав компонента входит собственная административная панель для настройки подключения и управления возможностями MCP.

Панель имеет адаптивный двухколоночный интерфейс. В ней можно посмотреть адрес API, скопировать его для подключения внешнего клиента, настроить параметры компонента и включить или отключить отдельные группы инструментов.

API-токен не отображается открыто при загрузке страницы. Администратор с необходимыми правами может отдельно посмотреть или скопировать его. Перевыпуск токена выполняется только по явному запросу с предупреждением о необходимости обновить подключения существующих клиентов.

Работа со структурой MODX

Одно из основных отличий MODX2MCP от обычного доступа к серверу — понимание структуры MODX.

Для агента ресурс остаётся ресурсом, шаблон — шаблоном, чанк — чанком, TV — TV-полем.

Это позволяет не просто изменять данные, а предварительно исследовать проект: искать связанные элементы, определять места использования и оценивать возможные последствия изменения.

В состав компонента входит граф зависимостей, который показывает связи между элементами MODX и помогает обнаруживать:

• использование чанков и сниппетов;
• связи шаблонов и TV-полей;
• вызовы одних элементов из других;
• отсутствующие зависимости;
• потенциально неиспользуемые элементы;
• участки проекта, которые могут быть затронуты изменением.

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

Контроль изменений

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

Начиная с версии 1.2.0 компонент поддерживает защиту от записи по устаревшему состоянию сайта. Агент может получить текущую ревизию проекта через

get_site_state

и передать предварительные условия для последующего изменения.

Если при выполнении защищённой операции обнаруживается, что данные уже изменены другим агентом или процессом, операция отклоняется с ошибкой

STALE_STATE

вместо записи поверх более свежего состояния.

В текущей версии усилена защита изменений TV-полей. Механизм CAS v2 позволяет проверять ревизию сайта и исходные значения изменяемых TV под общей блокировкой, а несколько значений сохранять в одной транзакции. Проверка исходного состояния также предусмотрена при изменении отдельных свойств элементов.

Важно: защита от конкурентных изменений действует при использовании соответствующих предварительных условий. Прямые обращения к API без этих условий не гарантируют защиту от перезаписи данных, изменённых другим агентом.

В компоненте предусмотрены:

• разделение операций чтения и изменения;
• предварительная проверка ряда действий;
• предварительный просмотр для некоторых изменяющих и массовых операций;
• ограничения для потенциально опасных операций;
• возможность отключения отдельных групп команд.

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

При этом MODX2MCP не гарантирует правильность решений самого ИИ-агента. Агент может неправильно понять поставленную задачу или выбрать неподходящий способ её выполнения.

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

Поэтому права и возможности агента должны соответствовать конкретному проекту и задачам, которые ему разрешено выполнять.

Совместимость

Эта версия компонента предназначена для MODX Revolution 2.8.x.

Для MODX Revolution 3.x выпускается отдельный компонент MODX3MCP.

Переход со старого MODX MCP

Если на сайте ранее был установлен пакет modxmcp, перед установкой MODX2MCP рекомендуется полностью удалить старый пакет через Менеджер пакетов.

После удаления установите новый пакет modx2mcp. Не оставляйте старый modxmcp и новый modx2mcp установленными одновременно.

При полном удалении старого пакета удаляются его настройки modxmcp.* и API-токен. После установки MODX2MCP необходимо проверить настройки и обновить токен в конфигурации MCP-клиента.

При последующих обновлениях уже установленного MODX2MCP существующие настройки и API-токен сохраняются.

Что потребуется дополнительно

Установка MODX2MCP — это только установка MODX-части системы.

После установки необходимо настроить API, обеспечить безопасное хранение токена и подключить внешний MCP-клиент. При новой установке API компонента по умолчанию выключен и требует явного включения администратором.

Для получения полноценного рабочего агента необходимо отдельно организовать внешний контур: подключить ИИ-агента, настроить его взаимодействие с MODX2MCP и определить правила его работы.

При необходимости можно дополнительно использовать Telegram-бота как общий интерфейс постановки задач. Это удобно, например, когда над одним проектом работают несколько человек.

Конкретная конфигурация зависит от того, какой ИИ, какой интерфейс и какой уровень автоматизации необходим пользователю.

Настройка внешнего контура обычно требует участия специалиста: подключение ИИ-агента, настройка взаимодействия с MODX2MCP, прав доступа и правил работы выполняются с учётом особенностей конкретного проекта.

Лицензия и исходный код

MODX2MCP распространяется бесплатно по лицензии MIT.

Исходный код проекта и готовые релизы находятся в открытом репозитории GitHub:
https://github.com/rumata-estor/modx3-mcp

Языки интерфейса и документация

Начиная с версии 1.2.4, административная панель MODX MCP и граф зависимостей переведены на 9 языков: русский (ru), английский (en), испанский (es), немецкий (de), французский (fr), украинский (uk), казахский на кириллице (kk), нидерландский (nl) и польский (pl).

Инструкции по установке, безопасности, настройкам и описания всех 192 MCP-инструментов доступны на этих языках. Названия API-команд, параметры и примеры кода остаются неизменными. Подробные технические схемы API и CHANGELOG ведутся на русском и английском.

Документация на 9 языках · Релиз 1.2.4 на GitHub