ave-cms/help/modules/mcp.md

MCP-интеграция

Модуль предоставляет безопасный канал чтения между AVE.cms и MCP-клиентом. Он не изменяет документы, настройки или файлы.

Что уже работает

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

В модуль входит отдельный Streamable HTTP транспорт. Он преобразует MCP-вызовы в запросы к защищённому JSON bridge и не получает прямого доступа к базе данных, конфигурации или файлам сайта. Поддерживаются современный протокол MCP 2026-07-28 и stateless-клиенты семейства 2025.

Установка и права

1. Установите и включите модуль MCP-интеграция в разделе Модули.
2. В Ролях и правах разрешите просмотр или управление модулем.
3. Откройте Модули → MCP-интеграция.
4. Создайте отдельное подключение для конкретного клиента.
5. Скопируйте секретный ключ. Повторно он не показывается.

В базе хранится SHA-256-хеш ключа. Подключение можно немедленно отозвать. Удаление модуля удаляет созданные им ключи.

Права токена не заменяют права пользователя. Для чтения нужны одновременно:

• scopes content.read и structure.read;
• права пользователя view_documents и view_public_site;
• установленный и включённый модуль.

Запуск MCP endpoint

Транспорт требует Node.js 20 или новее. Готовая команда показана на странице модуля. Базовый пример:

AVE_MCP_SITE_URL=https://example.org \
node modules/mcp/transport/dist/server.mjs

По умолчанию процесс слушает 127.0.0.1:3090, MCP endpoint доступен по адресу:

http://127.0.0.1:3090/mcp

Для удалённого клиента опубликуйте этот endpoint через HTTPS reverse proxy. Сам порт Node.js открывать в интернет не нужно. Публичное имя добавляется в списки разрешённых хостов:

AVE_MCP_SITE_URL=https://example.org \
AVE_MCP_ALLOWED_HOSTS=mcp.example.org \
AVE_MCP_ALLOWED_ORIGINS=mcp.example.org \
node modules/mcp/transport/dist/server.mjs

После создания подключения панель показывает готовый JSON с URL и заголовком Authorization. Токен передаётся MCP-клиентом при каждом обращении и повторно проверяется самим AVE.cms.

Инструменты и ресурс

Первая версия намеренно небольшая:

• diagnose.page — объясняет, из каких документов, полей, шаблонов, блоков, навигаций и модулей собрана публичная страница;
• requests.explain — объясняет, почему документ входит или не входит в результат сохранённого запроса;
• ave://introspection/contracts — описывает доступные read-only контракты.

Оба инструмента помечены как read-only, недеструктивные и идемпотентные. Команды сохранения, публикации, SQL, PHP, shell и работы с файлами не регистрируются.

Маршруты

Все ответы имеют режим read-only и содержат request_id.

GET /api/internal/v1/introspection/contracts
GET /api/internal/v1/introspection/page?target=/news/example
GET /api/internal/v1/introspection/request?request_id=2&document_id=42

Параметры публичной страницы для проверки запроса передаются строкой:

parameters=catalog%3Dbeds%26color%3Dwhite

или JSON-объектом:

{"catalog":"beds","color":"white"}

Пример запроса:

curl -H "Authorization: Bearer <token>" \
  "https://example.org/api/internal/v1/introspection/page?target=/news/example"

Для трассировки можно передать собственный безопасный идентификатор:

X-Request-ID: deployment-check-42

Ограничения безопасности

• только метод GET;
• не более 60 запросов в минуту на подключение;
• ответ не более 1 МБ;
• до 50 параметров страницы, общий размер до 10 КБ;
• переданный браузером Origin должен совпадать с сайтом;
• секретные поля и настройки маскируются до формирования ответа;
• исходники шаблонов, SQL, stack trace и абсолютные пути не возвращаются;
• PHP, произвольный SQL, shell и файловые операции отсутствуют.

Ошибки

Ошибка имеет стабильный код, понятное сообщение и признак возможности повтора:

{
  "success": false,
  "error": {
    "code": "entity_not_found",
    "message": "Документ не найден",
    "details": {},
    "retryable": false
  },
  "meta": {
    "request_id": "deployment-check-42",
    "mode": "read-only"
  }
}

Секреты и внутренние сообщения БД в ошибку не попадают.

Журнал

Фактические вызовы инструментов видны в разделе Система → События. В аудит записываются подключение, инструмент, состояние, длительность и request ID. Токен, содержимое документа и полный проверяемый URL не сохраняются.