Прежний docs/mcp.md перенесён без изменений текста в mcp-implementation-history.md с пометкой «исторический». Новый mcp.md (19 КБ) написан по коду: настройка сервера, подключение клиента, путь изменения, возможности, Route AI, webhook отзыва, восстановление базы, ограничения и проверки. Инструкция по включению дополнена правом mm:settings:admin и путём «Система» → «MCP»; входящие ссылки обновлены. Co-Authored-By: Claude Opus 5.5 <[email protected]>
18 KiB
MCP в MikroTik Manager
Manager работает как MCP-сервер. Внешний AI-клиент через него читает состояние серверов и готовит изменения RouterOS и приложения. Каждое изменение проходит один путь: план → проверка политики → подтверждение человеком, когда оно нужно → запись → проверка чтением.
Раздел в интерфейсе: «Система» → «MCP». По умолчанию MCP выключен.
| Документ | О чём |
|---|---|
| mcp-enable-guide.md | Включение по шагам: режимы, права, лимиты, защиты, временный допуск, остановка и отзыв, коды отказов |
| mcp-final-manifest.md | Что проверено, чем и с каким статусом |
| mcp-completion-plan.md | План завершения и открытые решения |
| mcp-implementation-history.md | Инженерная история реализации (прежнее содержимое этого файла) |
| mcp-implementation-plan.md | Исходный план реализации |
Настройка сервера
| Переменная | Назначение |
|---|---|
AUTH_REQUIRED=true, AUTH_ISSUER, AUTH_JWT_SECRET, CORS_ORIGIN |
Авторизация портала. Без неё /mcp и OAuth отвечают 503 |
MCP_PUBLIC_URL |
Внешний адрес MCP, например https://manager.example/mcp. Путь ровно /mcp, без query и логина в адресе. HTTPS обязателен, HTTP — только для localhost, 127.0.0.1, [::1] |
MCP_STATE_DIR |
Каталог состояния доступа: ключ шифрования, поколение доступа, отсечки отзыва портала и внешний журнал восстановления |
MCP_UI_URL |
Адрес веб-интерфейса для страницы согласия OAuth. По умолчанию CORS_ORIGIN |
MCP_PORTAL_WEBHOOK_SECRET |
Секрет webhook отзыва из портала, не короче 32 символов. Без него webhook отвечает 503 |
MCP_STATE_DIR:
- держите вне PostgreSQL и вне дампов, с доступом только у сервисного пользователя;
- несколько процессов backend должны видеть одно и то же состояние;
- при потере каталога все токены, неприменённые планы и зашифрованные данные MCP становятся недоступны.
Reverse proxy должен сохранять заголовок Host и пропускать /mcp, /oauth/* и /.well-known/*.
Миграции MCP применяются при старте backend. Для восстановления базы через MCP на сервере нужны pg_restore и psql, совместимые с версией PostgreSQL.
Подключение клиента
HTTP
Транспорт Streamable HTTP по адресу MCP_PUBLIC_URL, заголовок Authorization: Bearer <токен>.
- Принимаются только токены MCP вида
mmcp_…. JWT портала для MCP не подходит. - Токен выдаётся при создании подключения и показывается один раз: см. инструкцию.
- При перегрузке сервер отвечает 429 «Ресурс запросов MCP занят; повторите запрос позже». Повторите запрос позже.
Ожидание новых логов mm_logs_follow отменяется закрытием HTTP-ответа. Если клиент не умеет его закрывать, задавайте короткий waitSeconds или waitSeconds: 0.
stdio
Для клиентов, которые умеют только stdio, есть мост:
npm --prefix backend run build
npm --prefix backend run mcp:stdio
Мост читает MCP_URL и MCP_TOKEN из окружения и ходит в тот же HTTP endpoint с теми же правами и аудитом. Не передавайте токен в аргументах командной строки и не храните в Git.
OAuth
Для клиентов с OAuth вместо постоянного токена:
- «Настройки» → «OAuth-клиенты»: зарегистрируйте клиента с точными redirect URI. Допускаются HTTPS и loopback-адреса.
- При запросе доступа владелец выбирает подключение в «Разрешение OAuth-доступа». Клиент получает права ровно этого подключения.
Детали:
- публичный клиент без секрета, authorization code с PKCE
S256, scopemcp; - access token живёт до 15 минут и не дольше подключения;
- refresh token — до 30 дней, меняется при каждом обновлении;
- повторное использование старого refresh token отзывает всю цепочку;
- динамической регистрации клиентов нет.
Как проходит изменение
- План. Инструмент
*_planчитает текущее состояние и сохраняет план: конкретные ID, снимки, шаги, версию политики и срок. - Политика. Проверяются операция, серверы, права, лимиты и защиты. Решение — отказ, разрешение или требование подтверждения человеком. Правила — в инструкции.
- Применение.
mm_change_applyс ID плана. Перед записью Manager:- повторно проверяет доступ и бюджет;
- сверяет снимки: если объект изменился после подготовки, план отклоняется;
- сохраняет намерение до первой записи.
- Проверка. Каждый шаг проверяется чтением с роутера. Ход и итог —
mm_operation_getи «Планы и операции» → «Выполнение операций».
Гарантии и пределы:
- Повтор с тем же ключом идемпотентности не повторяет запись.
- Исход не повторяется автоматически. Если процесс потерян или ответ роутера не подтверждён, операция получает «Исход не подтверждён».
- Частичный результат. Если проверка после записи не прошла, операция получает «Выполнена частично».
- Запись в глобальную конфигурацию. Одновременно идёт одна такая запись — из интерфейса или из MCP. Ожидание до 30 секунд, затем
CONFIGURATION_BUSY. - Очередь исполнителя — не больше 100 ожидающих и выполняющихся операций.
Разбор результата:
mm_operation_reconcileчитает текущее состояние объектов операции.mm_operation_recovery_planготовит отдельный обратный план для проверенных созданий и изменений без внешних правок. Он подтверждается человеком.- Универсального отката удалений и сервисных операций нет. Для них есть восстановление ревизий:
mm_recursive_revision_restore_plan,mm_firewall_revision_restore_plan,mm_gre_revision_restore_plan,mm_wireguard_revision_restore_plan,mm_ipsec_revision_restore_plan.
В интерфейсе то же — «Планы и операции» → «Сверка и восстановление».
Возможности
Точный список инструментов — GET /api/mcp/catalog. Соответствие REST-маршрутов инструментам — «Настройки» → «Покрытие REST через MCP».
Новые инструменты не попадают в существующие подключения сами: операции выдаются подключению явно.
| Область | Что доступно |
|---|---|
| Серверы | каталог, опрос, снимки, WAN, настройки API-ping, типизированная диагностика терминала, добавление, изменение и удаление серверов |
| Пользователи Manager | каталог /users, серверные права и привязки интерфейсов. Это не учётные записи портала и не пользователи RouterOS |
| Логи и события | поиск, контекст, ожидание новых записей, экспорт, настройки сборщика; события и оповещения, Telegram |
| Мониторинг | uptime, ping- и speed-пробы, статистика, трафик и NetFlow, Internet path |
| Интерфейсы и адреса RouterOS | Ethernet, bridge, порты и VLAN bridge, VLAN, адреса и маршруты IPv4/IPv6, таблицы и правила маршрутизации, VRF, RPF и hash policy, IPv6 ND |
| Туннели | GRE, WireGuard и его peers, VXLAN, IPsec: сервер, пользователи, peers, сертификаты |
| Маршрутизация | BGP: сессии, instances, connections, фильтры, Community, export policy, EvoBGP; OSPF: templates, соседи, instances, areas, оптимизация; BFD; рекурсивные маршруты; ECMP; фильтры маршрутизации; firewall |
| Прочее | контейнеры, сертификаты, GeoIP, резервные копии, планировщик, восстановление базы приложения |
Типизированные объекты RouterOS доступны и в интерфейсе: «Интерфейсы» — чтение и подготовка планов от имени выбранного подключения.
Наличие инструмента не означает, что каждый сценарий раздела проверен на стенде. Статусы — в манифесте.
Route AI
Постоянный контроллер переключает маршруты по профилю через обычные планы MCP. Настройка, требования к допуску и причины остановки — в инструкции.
Проверка пути. mm_route_path_verify выполняет ограниченные ping и traceroute зарегистрированного пути. Это проверка контрольных пакетов, а не всего пользовательского трафика. Пропущенные промежуточные hops остаются неизвестными.
Независимый канал управления — другой IP того же RouterOS. Его регистрирует человек: «Настройки» → «Независимый канал управления». Manager проверяет стабильный ID устройства и доступность. Что путь физически независим, подтверждает администратор.
Автоматическое восстановление маршрутов недоступно, профиль с ним не включается.
Отзыв доступа порталом
Портал сообщает Manager о смене прав, отключении пользователя или отзыве его сессий.
Формат запроса:
-
запрос:
POST /_internal/mcp/portal/revocations; -
тело: JSON не больше 4096 байт:
{"eventId":"<UUID>","userId":"<sub из JWT>","type":"permissions.changed"} -
type— одно из значений:permissions.changed,user.disabled,sessions.revoked.
Подпись:
X-MM-Timestamp— время в Unix-секундах, допустимое расхождение ±5 минут;X-MM-Signature—sha256=<hex>, HMAC-SHA256 с ключомMCP_PORTAL_WEBHOOK_SECRETот строкиtimestamp + "." + точные байты тела.
Повторы. Повтор с тем же eventId и тем же телом принимается без повторного эффекта. Другое тело с тем же eventId отклоняется (409).
Результат. Отзываются подключения пользователя, выданные до события, вместе с токенами и временными допусками. Отсечка хранится и в MCP_STATE_DIR, поэтому переживает восстановление старой базы.
Восстановление базы приложения
Восстановление базы приложения через MCP:
- Администратор (
mm:settings:admin) загружает архив в «Настройки». Требования к архиву:- формат PostgreSQL custom (
PGDMP), до 64 МиБ; - хранится зашифрованным, до 15 минут;
- одновременно не больше четырёх архивов.
- формат PostgreSQL custom (
- Клиент получает ссылку на архив и SHA-256 и вызывает
mm_database_restore_plan. - План требует подтверждения человеком и глобального доступа ко всем серверам.
Ограничения:
- произвольные пути, SQL и загрузка архива самим агентом не поддерживаются;
- до записи Manager аннулирует все доступы MCP (поколение доступа): после восстановления подключения создаются заново;
- потерянная команда не повторяется.
Восстановление может удалить запись об операции из базы. Квитанция хранится вне базы: в интерфейсе или GET /api/mcp/database/receipts/:id.
Ограничения
Что не реализовано:
- Автоматическое восстановление маршрутов и автоматический обратный шаг Route AI. Нет источника событий RouterOS, который замечает пропуски.
- Универсальный откат удалений и сервисных операций. Только восстановление ревизий, где оно есть.
- Автоматический повтор операции с неподтверждённым исходом. Его нет намеренно; разбор — сверкой.
Что Manager не доказывает:
- Физическую независимость путей. Её подтверждает администратор. Третьего независимого узла для проверки на стенде не было.
- Путь всего пользовательского трафика. Проверка пути смотрит только на контрольные пакеты.
Известные недостатки:
- VRF поверх активного GRE. Создание может закончиться «Выполнена частично», хотя VRF на роутере создан. Проверяйте сверкой.
- Лимит памяти 2 ГиБ для всей установки не подтверждён.
Решения по открытым пунктам — в плане завершения.
Проверки для разработчиков
Из корня репозитория:
npm run test:mcp
npm --prefix backend run test:mcp:pg
npm --prefix backend run test:mcp:pg:all
npm --prefix backend run test:mcp:pg:sharded
npm --prefix backend run build
Что делают наборы:
test:mcpв корне — тесты веб-раздела и сценарии Playwrightplaywright.mcp.config.ts.test:mcp:pgподнимает временный PostgreSQL 18 со своими миграциями, имитатором RouterOS и настоящими HTTP- и stdio-клиентами. База приложения не используется.:pg:allдобавляет профили backend.:pg:shardedдаёт то же покрытие, чтоtest:mcp:pg, но медленные проверки идут параллельными шардами.
Для проверки восстановления нужны pg_dump и pg_restore PostgreSQL 18: в PATH или в каталоге из MMAPP_PG_CLIENT_BIN. Встроенный PostgreSQL для Windows этих утилит не содержит.