# 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 или новее. Готовая команда показана на странице
модуля. Базовый пример:

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

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

```text
http://127.0.0.1:3090/mcp
```

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

```bash
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`.

```text
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
```

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

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

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

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

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

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

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

```text
X-Request-ID: deployment-check-42
```

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

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

## Ошибки

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

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

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

## Журнал

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