# MCP в MikroTik Manager Manager работает как MCP-сервер. Внешний AI-клиент через него читает состояние серверов и готовит изменения RouterOS и приложения. Каждое изменение проходит один путь: план → проверка политики → подтверждение человеком, когда оно нужно → запись → проверка чтением. Раздел в интерфейсе: «Система» → «MCP». По умолчанию MCP выключен. | Документ | О чём | | --- | --- | | [mcp-enable-guide.md](mcp-enable-guide.md) | Включение по шагам: режимы, права, лимиты, защиты, временный допуск, остановка и отзыв, коды отказов | | [mcp-final-manifest.md](mcp-final-manifest.md) | Что проверено, чем и с каким статусом | | [mcp-completion-plan.md](mcp-completion-plan.md) | План завершения и открытые решения | | [mcp-implementation-history.md](mcp-implementation-history.md) | Инженерная история реализации (прежнее содержимое этого файла) | | [mcp-implementation-plan.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 не подходит. - Токен выдаётся при создании подключения и показывается один раз: см. [инструкцию](mcp-enable-guide.md). - При перегрузке сервер отвечает 429 «Ресурс запросов MCP занят; повторите запрос позже». Повторите запрос позже. Ожидание новых логов `mm_logs_follow` отменяется закрытием HTTP-ответа. Если клиент не умеет его закрывать, задавайте короткий `waitSeconds` или `waitSeconds: 0`. ### stdio Для клиентов, которые умеют только stdio, есть мост: ```powershell npm --prefix backend run build ``` ```powershell 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 отзывает всю цепочку; - динамической регистрации клиентов нет. ## Как проходит изменение 1. **План.** Инструмент `*_plan` читает текущее состояние и сохраняет план: конкретные ID, снимки, шаги, версию политики и срок. 2. **Политика.** Проверяются операция, серверы, права, лимиты и защиты. Решение — отказ, разрешение или требование подтверждения человеком. Правила — в [инструкции](mcp-enable-guide.md). 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_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 доступны и в интерфейсе: «Интерфейсы» — чтение и подготовка планов от имени выбранного подключения. Наличие инструмента не означает, что каждый сценарий раздела проверен на стенде. Статусы — в [манифесте](mcp-final-manifest.md). ## Route AI Постоянный контроллер переключает маршруты по профилю через обычные планы MCP. Настройка, требования к допуску и причины остановки — в [инструкции](mcp-enable-guide.md#постоянный-контроллер-route-ai). **Проверка пути.** `mm_route_path_verify` выполняет ограниченные ping и traceroute зарегистрированного пути. Это проверка контрольных пакетов, а не всего пользовательского трафика. Пропущенные промежуточные hops остаются неизвестными. **Независимый канал управления** — другой IP того же RouterOS. Его регистрирует человек: «Настройки» → «Независимый канал управления». Manager проверяет стабильный ID устройства и доступность. Что путь физически независим, подтверждает администратор. **Автоматическое восстановление маршрутов недоступно**, профиль с ним не включается. ## Отзыв доступа порталом Портал сообщает Manager о смене прав, отключении пользователя или отзыве его сессий. **Формат запроса:** - запрос: `POST /_internal/mcp/portal/revocations`; - тело: JSON не больше 4096 байт: ```json {"eventId":"","userId":"","type":"permissions.changed"} ``` - `type` — одно из значений: `permissions.changed`, `user.disabled`, `sessions.revoked`. **Подпись:** - `X-MM-Timestamp` — время в Unix-секундах, допустимое расхождение ±5 минут; - `X-MM-Signature` — `sha256=`, 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 не доказывает:** - **Физическую независимость путей.** Её подтверждает администратор. Третьего независимого узла для проверки на стенде не было. - **Путь всего пользовательского трафика.** Проверка пути смотрит только на контрольные пакеты. **Известные недостатки:** - **VRF поверх активного GRE.** Создание может закончиться «Выполнена частично», хотя VRF на роутере создан. Проверяйте сверкой. - **Лимит памяти 2 ГиБ** для всей установки не подтверждён. Решения по открытым пунктам — в [плане завершения](mcp-completion-plan.md). ## Проверки для разработчиков Из корня репозитория: ```powershell npm run test:mcp ``` ```powershell npm --prefix backend run test:mcp:pg ``` ```powershell npm --prefix backend run test:mcp:pg:all ``` ```powershell npm --prefix backend run test:mcp:pg:sharded ``` ```powershell 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`, но медленные проверки идут параллельными шардами. Для проверки восстановления нужны `pg_dump` и `pg_restore` PostgreSQL 18: в `PATH` или в каталоге из `MMAPP_PG_CLIENT_BIN`. Встроенный PostgreSQL для Windows этих утилит не содержит.