Сервер Grav MCP¶

Сервер Grav MCP открывает сайт Grav 2.0 агентным ИИ-клиентам через Model Context Protocol (MCP). Это отдельное приложение на Node.js, распространяемое как пакет grav-mcp в npm. Это не плагин Grav: он работает внутри вашего ИИ-клиента (Claude Code, Claude Desktop, Cursor или любого клиента, поддерживающего MCP) и общается с вашим сайтом по HTTP через официальный плагин API Grav.

Принцип устройства прост: Admin2 — клиент для людей, сервер MCP — клиент для ИИ, и оба идут через один и тот же API. У сервера MCP нет привилегированного чёрного хода в Grav. Каждая выполняемая им операция — это аутентифицированный HTTP-запрос с проверкой разрешений к /api/v1, точно как у любого другого потребителя API.

Предупреждение

Для сервера MCP нужен установленный и включённый на целевом сайте Grav плагин API. Сам сервер MCP не содержит логики работы с контентом; это слой трансляции между вызовами инструментов MCP и REST API Grav.

Архитектура¶

┌─────────────────┐   stdio / HTTP    ┌──────────────┐   HTTPS + X-API-Key   ┌──────────────────┐
│   AI Client     │ ◀──────────────▶  │  grav-mcp    │ ◀───────────────────▶ │  Grav API Plugin │
│ (Claude, etc.)  │   MCP protocol    │ (Node.js)    │   REST /api/v1        │  (PHP, on site)  │
└─────────────────┘                   └──────────────┘                       └──────────────────┘

ИИ-клиент запускает grav-mcp как подпроцесс (транспорт stdio) или подключается к работающему экземпляру (транспорт HTTP).
grav-mcp объявляет клиенту свой каталог инструментов, ресурсов и подсказок.
Когда модель вызывает инструмент, grav-mcp превращает вызов в аутентифицированный HTTP-запрос к API Grav.
Плагин API аутентифицирует запрос, проверяет разрешения, выполняет операцию с файловой системой и возвращает структурированный JSON.

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

Требования¶

Node.js 18+ на машине, где запущен ИИ-клиент.
Сайт Grav 2.0 с установленным и включённым плагином API.
Ключ API, созданный для пользователя, от имени которого должен действовать ИИ.

Установка и настройка¶

Вручную устанавливать ничего не нужно. Пакет grav-mcp запускается по требованию через npx, поэтому вся настройка происходит в вашем ИИ-клиенте.

1. Создайте ключ API¶

На сайте Grav создайте ключ для подходящего пользователя (перед выбором пользователя см. Разрешения и безопасность):

bin/plugin api keys:generate --user=admin --name="Claude MCP"

Ключ (с префиксом grav_) показывается один раз. Скопируйте его сразу. Команды управления ключами (keys:list, keys:revoke) описаны в справочнике Аутентификация API.

2. Зарегистрируйте сервер в ИИ-клиенте¶

Сервер MCP настраивается через две переменные окружения: GRAV_API_URL (базовый URL API вашего сайта) и GRAV_API_KEY (только что созданный ключ).

Claude Code / Claude Desktop / Cursor и большинство клиентов MCP используют стандартный блок конфигурации mcpServers:

{
  "mcpServers": {
    "grav": {
      "command": "npx",
      "args": ["-y", "grav-mcp"],
      "env": {
        "GRAV_API_URL": "https://my-site.example/api",
        "GRAV_API_KEY": "grav_your_api_key_here"
      }
    }
  }
}

Перезапустите (или переподключите) клиент — и полный набор инструментов Grav станет доступен.

3. (Необязательно) Запуск напрямую для тестирования¶

Та же конфигурация работает в командной строке:

GRAV_API_URL=https://my-site.example/api GRAV_API_KEY=grav_abc123 npx grav-mcp

Справочник конфигурации¶

Каждый параметр можно задать переменной окружения или флагом CLI. Флаги CLI имеют приоритет.

Переменная окружения	Флаг CLI	Обязательный	Описание
`GRAV_API_URL`	`--url`	Да	Базовый URL API Grav (например, `https://my-site.example/api`).
`GRAV_API_KEY`	`--key`	Да	Ключ API для аутентификации. Должен начинаться с `grav_`.
`GRAV_ENVIRONMENT`	`--environment`	Нет	Нацеливает на конкретное окружение `user/env/*` для областей конфигурации (передаётся заголовком `X-Config-Environment`).
—	`--transport`	Нет	`stdio` (по умолчанию) или `http`.
—	`--port`	Нет	Порт для транспорта HTTP. По умолчанию `3100`.

Транспорты¶

stdio (по умолчанию)¶

Транспорт по умолчанию. ИИ-клиент запускает grav-mcp как дочерний процесс и общается через стандартный ввод/вывод. Это правильный выбор для локальных однопользовательских клиентов, таких как Claude Code, Claude Desktop и Cursor.

HTTP¶

Для удалённых или многопользовательских развёртываний запустите долгоживущий сервер, к которому клиенты подключаются по HTTP:

npx grav-mcp --url https://my-site.example/api --key grav_abc123 --transport http --port 3100

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

Сервер предоставляет 70 семантических инструментов в 11 доменах. Это именованные типизированные операции (не сырые эндпоинты REST), описанные на языке, о котором модель может рассуждать.

Страницы (10)¶

Инструмент	Назначение
`list_pages`	Вывод страниц в дереве контента.
`get_page`	Получение одной страницы (метаданные + контент).
`create_page`	Создание новой страницы.
`update_page`	Обновление метаданных и/или контента страницы.
`delete_page`	Удаление страницы.
`move_page`	Перемещение страницы на новый маршрут.
`copy_page`	Копирование страницы на новый маршрут.
`reorder_pages`	Изменение порядка соседних страниц.
`batch_pages`	Атомарное применение нескольких операций над страницами.
`reorganize_pages`	Массовая реорганизация поддерева одной операцией.

Мультиязычность (5)¶

Инструмент	Назначение
`list_languages`	Вывод настроенных языков сайта.
`get_page_translations`	Вывод переводов страницы.
`create_translation`	Создание перевода страницы.
`adopt_page_language`	Принятие/назначение языка для страницы.
`compare_translations`	Сравнение двух языковых версий страницы.

Медиафайлы (8)¶

Инструмент	Назначение
`list_page_media`	Вывод медиафайлов, прикреплённых к странице.
`upload_page_media`	Загрузка медиафайлов на страницу.
`delete_page_media`	Удаление медиафайлов со страницы.
`list_site_media`	Вывод медиафайлов уровня сайта.
`upload_site_media`	Загрузка медиафайлов уровня сайта.
`delete_site_media`	Удаление медиафайлов уровня сайта.
`create_media_folder`	Создание папки медиафайлов.
`manage_media_folder`	Переименование, перемещение или удаление папки медиафайлов.

Конфигурация (3)¶

Инструмент	Назначение
`list_config_scopes`	Вывод доступных областей конфигурации.
`get_config`	Чтение области конфигурации (возвращает ETag).
`update_config`	Обновление области конфигурации (с проверкой ETag, с учётом окружения).

Пользователи (6)¶

Инструмент	Назначение
`list_users`	Вывод учётных записей пользователей.
`get_user`	Получение одного пользователя.
`create_user`	Создание пользователя.
`update_user`	Обновление пользователя.
`delete_user`	Удаление пользователя.
`manage_api_keys`	Вывод, создание и отзыв ключей API пользователя.

Менеджер пакетов (9)¶

Инструмент	Назначение
`list_packages`	Вывод установленных плагинов и тем.
`get_package_info`	Получение сведений о пакете.
`search_packages`	Поиск в репозитории GPM.
`check_updates`	Проверка доступных обновлений.
`install_package`	Установка плагина или темы (с разрешением зависимостей схем).
`update_package`	Обновление одного пакета.
`update_all_packages`	Обновление всех пакетов.
`upgrade_grav`	Обновление ядра Grav.
`remove_package`	Удаление пакета.

Система (10)¶

Инструмент	Назначение
`get_system_info`	Получение информации о системе и окружении.
`clear_cache`	Очистка кэша Grav.
`get_logs`	Чтение системных журналов.
`create_backup`	Создание резервной копии.
`list_backups`	Вывод резервных копий.
`get_scheduler`	Просмотр заданий и состояния планировщика.
`run_scheduler`	Запуск планировщика.
`list_environments`	Вывод настроенных окружений.
`create_environment`	Создание нового окружения.
`get_password_policy`	Чтение действующей политики паролей.

Панель управления и отчёты (7)¶

Инструмент	Назначение
`get_dashboard_stats`	Получение статистики панели управления.
`get_notifications`	Вывод уведомлений панели управления.
`dismiss_notification`	Скрытие уведомления.
`run_reports`	Запуск диагностических отчётов.
`get_dashboard_widgets`	Вывод виджетов панели управления.
`update_dashboard_layout`	Обновление макета панели управления текущего пользователя.
`update_site_dashboard_layout`	Обновление макета панели управления по умолчанию для всего сайта.

Вебхуки (4)¶

Инструмент	Назначение
`list_webhooks`	Вывод настроенных вебхуков.
`manage_webhook`	Создание, обновление и удаление вебхука.
`get_webhook_deliveries`	Просмотр журнала доставок вебхука.
`test_webhook`	Отправка тестовой нагрузки на вебхук.

Схемы и структура (6)¶

Инструмент	Назначение
`list_page_templates`	Вывод доступных шаблонов страниц.
`get_blueprint`	Получение вычисленной схемы.
`get_permissions`	Получение каталога разрешений.
`get_taxonomy`	Получение типов и значений таксономии.
`upload_blueprint_file`	Загрузка файла схемы.
`delete_blueprint_file`	Удаление файла схемы.

Обнаружение плагинов (2)¶

Инструмент	Назначение
`discover_plugins`	Обнаружение фич админки, предоставляемых установленными плагинами.
`plugin_action`	Запуск действия, предоставляемого плагином.

Ресурсы¶

Помимо инструментов сервер предоставляет 5 ресурсов, которые модель может прочитать для контекста, не выполняя действие:

URI ресурса	Описание
`grav://system/info`	Информация о системе и окружении.
`grav://user/permissions`	Действующие разрешения аутентифицированного пользователя API.
`grav://languages`	Настроенные языки сайта.
`grav://templates`	Доступные шаблоны страниц.
`grav://taxonomy`	Типы таксономии и их значения.

Подсказки¶

Сервер поставляется с 6 подсказками для рабочих процессов, которые упаковывают типичные многошаговые задачи в единый пошаговый сценарий:

Подсказка	Рабочий процесс
`create_blog_post`	Пошаговое создание записи блога (шаблон, метаданные, медиафайлы, таксономия).
`translate_page`	Перевод страницы на другой настроенный язык.
`site_health_check`	Всесторонняя проверка состояния сайта.
`content_audit`	Аудит качества контента и метаданных.
`plugin_setup`	Поиск, установка и настройка плагина.
`bulk_update`	Массовое обновление метаданных многих страниц.

Аутентификация¶

Каждый запрос сервера MCP несёт ключ API в заголовке X-API-Key:

X-API-Key: grav_abc123...

Это та же аутентификация по ключу API, что описана в справочнике Аутентификация API. Когда задан GRAV_ENVIRONMENT, сервер также отправляет заголовок X-Config-Environment, чтобы чтение и запись конфигурации нацеливались на правильное окружение.

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

Разрешения и безопасность¶

Самое важное, что нужно понять о модели безопасности сервера MCP: он наследует разрешения пользователя, которому принадлежит его ключ API, и ничего больше. Отдельного набора разрешений «для ИИ» нет. Те же разрешения api.pages.write, api.config.write, api.gpm.write (и так далее), которые ограничивают любого потребителя API, ограничивают и ИИ.

Это значит, что вы управляете тем, что может делать ИИ, выбирая пользователя, которому выдан ключ:

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

Предупреждение

Создайте отдельного пользователя с минимальными правами для доступа ИИ, а не используйте свою основную учётную запись администратора. Ключ никогда не может превысить разрешения пользователя, которому он принадлежит, поэтому учётная запись пользователя — ваша граница безопасности. Ограничение разрешений для отдельного ключа пока не применяется независимо от пользователя.

Безопасность параллелизма¶

Вся запись конфигурации и страниц проходит через оптимистичный контроль параллелизма на основе ETag в API. Сервер читает ETag при GET и отправляет его обратно в If-Match при записи. Если ресурс за это время изменился (например, человек отредактировал ту же страницу в Admin2), API возвращает 409 Conflict вместо молчаливой перезаписи, и агент должен заново получить данные и согласовать их.

Наблюдаемость¶

Сервер MCP не добавляет собственный журнал аудита. Вместо этого каждая запись через API вызывает структурированное событие (onApiPageCreated, onApiConfigUpdated и остальные из семейства onApi*), а эти события питают систему вебхуков API. Чтобы записывать изменения, инициированные ИИ, направьте вебхук на свой эндпоинт журналирования или уведомлений. Доставки вебхуков подписываются HMAC, поэтому можно проверить их происхождение. Полный список событий см. в справочнике События API.

Разработка и поддержка¶

Для участников, работающих над самим сервером, в репозитории есть обычные скрипты:

npm run typecheck        # Проверка типов в исходниках TypeScript
npm test                 # Запуск набора модульных тестов
npm run build            # Компиляция в dist/
npm run audit:api        # Проверка покрытия инструментами работающего плагина API
npm run changelog:since  # Отчёт об изменениях плагина API с последней проверенной версии

Скрипты audit:api и changelog:since нужны, чтобы каталог инструментов оставался синхронизированным с развивающимся плагином API: они сравнивают аннотации @api METHOD /path сервера с фактическими маршрутами плагина.

См. также¶

REST API — API, на котором построен сервер MCP.
Аутентификация API — создание ключей и управление ими.
События API — события, питающие вебхуки и аудит.
grav-mcp на GitHub
grav-plugin-api на GitHub
Model Context Protocol