Прежний 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]>
228 lines
18 KiB
Markdown
228 lines
18 KiB
Markdown
# 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":"<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 не доказывает:**
|
||
|
||
- **Физическую независимость путей.** Её подтверждает администратор. Третьего независимого узла для проверки на стенде не было.
|
||
- **Путь всего пользовательского трафика.** Проверка пути смотрит только на контрольные пакеты.
|
||
|
||
**Известные недостатки:**
|
||
|
||
- **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 этих утилит не содержит.
|