Files
MikrotikManager/docs/mcp.md
T
DenozordecandClaude Opus 5.5 d586f87009 fix(docs): MCP — публичный маршрут в deploy, срок OAuth и проверенные утверждения
Поставляемый deploy не передаёт backend /mcp, /oauth/* и /.well-known/*:
записано как ограничение и открытое решение владельца. OAuth-токены
ограничены сроком прав владельца. Добавлен mm_filter_revision_restore_plan,
требование pg_dump/pg_restore для test:mcp:pg*, путь к старым версиям в
истории Git. Запись плана уточняет, что проверено по коду.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-11-21 21:28:44 +07:00

20 KiB
Raw Permalink Blame History

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 и передавать backend пути /mcp, /oauth/* и /.well-known/*.

Поставляемые deploy/docker-compose*.yml этого не делают. Traefik отдаёт домен frontend, а frontend передаёт backend только /api и /health. Путь /mcp на основном домене — страница веб-раздела. Для внешнего клиента нужен отдельный маршрут на backend:

  • например, отдельный хост mcp.manager.example для /mcp, /oauth/* и /.well-known/*;
  • MCP_PUBLIC_URL с этим хостом;
  • MCP_UI_URL — адрес веб-интерфейса.

На стенде клиент подключался к backend напрямую через туннель. Публичный маршрут не проверялся.

Webhook отзыва /_internal/mcp/portal/revocations тоже идёт на backend, а не через frontend. Портал должен достучаться до него по внутренней сети или по отдельному маршруту.

Миграции 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 вместо постоянного токена:

  1. «Настройки» → «OAuth-клиенты»: зарегистрируйте клиента с точными redirect URI. Допускаются HTTPS и loopback-адреса.
  2. При запросе доступа владелец выбирает подключение в «Разрешение OAuth-доступа». Клиент получает права ровно этого подключения.

Детали:

  • публичный клиент без секрета, authorization code с PKCE S256, scope mcp;
  • access token живёт до 15 минут и не дольше подключения;
  • refresh token — до 30 дней, меняется при каждом обновлении;
  • повторное использование старого refresh token отзывает всю цепочку;
  • динамической регистрации клиентов нет;
  • OAuth-токены, как и обычный токен, работают только пока действуют права владельца подключения: не дольше 24 часов после их подтверждения, см. инструкцию. Refresh token этот срок не продлевает.

Как проходит изменение

  1. План. Инструмент *_plan читает текущее состояние и сохраняет план: конкретные ID, снимки, шаги, версию политики и срок.
  2. Политика. Проверяются операция, серверы, права, лимиты и защиты. Решение — отказ, разрешение или требование подтверждения человеком. Правила — в инструкции.
  3. Применение. mm_change_apply с ID плана. Перед записью Manager:
    • повторно проверяет доступ и бюджет;
    • сверяет снимки: если объект изменился после подготовки, план отклоняется;
    • сохраняет намерение до первой записи.
  4. Проверка. Каждый шаг проверяется чтением с роутера. Ход и итог — mm_operation_get и «Планы и операции» → «Выполнение операций».

Гарантии и пределы:

  • Повтор с тем же ключом идемпотентности не повторяет запись.
  • Исход не повторяется автоматически. Если процесс потерян или ответ роутера не подтверждён, операция получает «Исход не подтверждён».
  • Частичный результат. Если проверка после записи не прошла, операция получает «Выполнена частично».
  • Запись в глобальную конфигурацию. Одновременно идёт одна такая запись — из интерфейса или из MCP. Ожидание до 30 секунд, затем CONFIGURATION_BUSY.
  • Очередь исполнителя — не больше 100 ожидающих и выполняющихся операций.

Разбор результата:

  • mm_operation_reconcile читает текущее состояние объектов операции.
  • mm_operation_recovery_plan готовит отдельный обратный план для проверенных созданий и изменений без внешних правок. Он подтверждается человеком.
  • Универсального отката удалений и сервисных операций нет. Для них есть восстановление ревизий: mm_recursive_revision_restore_plan, mm_filter_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:

  1. Администратор (mm:settings:admin) загружает архив в «Настройки». Требования к архиву:
    • формат PostgreSQL custom (PGDMP), до 64 МиБ;
    • хранится зашифрованным, до 15 минут;
    • одновременно не больше четырёх архивов.
  2. Клиент получает ссылку на архив и SHA-256 и вызывает mm_database_restore_plan.
  3. План требует подтверждения человеком и глобального доступа ко всем серверам.

Ограничения:

  • произвольные пути, SQL и загрузка архива самим агентом не поддерживаются;
  • до записи Manager аннулирует все доступы MCP (поколение доступа): после восстановления подключения создаются заново;
  • потерянная команда не повторяется.

Восстановление может удалить запись об операции из базы. Квитанция хранится вне базы: в интерфейсе или GET /api/mcp/database/receipts/:id.

Ограничения

Что не реализовано:

  • Автоматическое восстановление маршрутов и автоматический обратный шаг Route AI. Нет источника событий RouterOS, который замечает пропуски.
  • Универсальный откат удалений и сервисных операций. Только восстановление ревизий, где оно есть.
  • Автоматический повтор операции с неподтверждённым исходом. Его нет намеренно; разбор — сверкой.

Что Manager не доказывает:

  • Физическую независимость путей. Её подтверждает администратор. Третьего независимого узла для проверки на стенде не было.
  • Путь всего пользовательского трафика. Проверка пути смотрит только на контрольные пакеты.

Известные недостатки:

  • Публичный маршрут MCP в поставляемом deploy. Его нет, настраивается вручную: см. раздел о настройке сервера выше.
  • 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 в корне — тесты веб-раздела и сценарии Playwright playwright.mcp.config.ts.
  • test:mcp:pg поднимает временный PostgreSQL 18 со своими миграциями, имитатором RouterOS и настоящими HTTP- и stdio-клиентами. База приложения не используется.
  • :pg:all добавляет профили backend.
  • :pg:sharded даёт то же покрытие, что test:mcp:pg, но медленные проверки идут параллельными шардами.

Наборам test:mcp:pg* нужны pg_dump и pg_restore PostgreSQL 18: в PATH или в каталоге из MMAPP_PG_CLIENT_BIN. Без них основной набор падает с DATABASE_DUMP_TOOL_UNAVAILABLE. Встроенный PostgreSQL для Windows этих утилит не содержит.