Files
MikrotikManager/docs/mcp.md
T
DenozordecandClaude Opus 5.5 c1abfffe26 chore(docs): пользовательская документация MCP вместо 417 КБ инженерных записей
Прежний 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]>
2026-11-21 21:25:01 +07:00

228 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 этих утилит не содержит.