diff --git a/docs/mcp-completion-plan.md b/docs/mcp-completion-plan.md index 67e226dc..d05b9ba3 100644 --- a/docs/mcp-completion-plan.md +++ b/docs/mcp-completion-plan.md @@ -117,7 +117,7 @@ ## Этап 5. Закрытие (FINAL-2 и FINAL-3) - [x] Манифест: критерий плана → доказательство → статус, без перекраски `failed` и `unknown` — 2026-11-21, [mcp-final-manifest.md](mcp-final-manifest.md): исходные критерии реестра по направлениям POLL, DB, ROUTING, NATIVE, PATHS, EXTERNAL-UI, FINAL с доказательствами и статусами; отдельно история отказов (13 строк) и критерии вне плана завершения со статусом «не проверено». Решения по открытым строкам — за владельцем -- [ ] Инструкция по включению: наблюдение → подтверждения → ограниченная автономность +- [x] Инструкция по включению: наблюдение → подтверждения → ограниченная автономность — 2026-11-21, [mcp-enable-guide.md](mcp-enable-guide.md): права портала, `MCP_PUBLIC_URL` и `MCP_STATE_DIR`, три шага с переходами и возвратом, срок прав владельца (до 24 часов), часовой бюджет в объектах, срок плана 5 и 15 минут, защиты, временный допуск, Route AI без автоматического восстановления, пауза, отзыв и аварийная остановка, частые отказы. Надписи сверены с `components/mcp/*.tsx`, числа и коды — с backend и контрактами. На стенде проверен только режим «С подтверждением»; «Наблюдатель» и «Автономный» покрыты `policy.test.ts` - [x] Проверить, что MCP и контроллер выключены по умолчанию — 2026-11-21: `mcp_settings.enabled` и `mcp_routing_profiles.enabled` по умолчанию `false` (`0015_mcp.sql`), `autoRecovery` по умолчанию `false` (контракт), выключенный MCP отказывает токену `MCP_DISABLED`/503 (`store.ts`), воркер не вызывает контроллер при выключенном MCP (`workers.ts`). Проверки на свежей базе добавлены в `integration.test.ts` (первичный шард `test-mcp-postgres-sharded.mjs`) - [ ] Сократить `docs/mcp.md` (417 КБ) до пользовательской документации - [ ] PR в `main` @@ -151,6 +151,7 @@ | 2026-11-20 | B2 (capacity336, nonce `5945935965481c83`) — `failed` на 169 операциях и 163 архивах после 2 ч 41 мин. Разбор очереди архивов держался до конца. Node завершился через `abort()`, текст ошибки не сохранился. Гипотеза — рост кучи с каждой операцией (время операции растёт с 5 до 22 с за 70 операций). Пакет снят, VPS свободен, повтора нет; пункт B2 открыт | | 2026-11-20 | Причина установлена: продукт создавал `AsyncLocalStorage` на каждый опрос (Node держит их вечно), исправлено в `29998815`. `mmapp-test` переразвёрнут (Gitea `2745`), B1 повторён (12,1 с), **B2 принят**: 337/336/1348, 0 ошибок воркера, 5 ч 40 мин, очистка подтверждена. Оба пункта прогона B закрыты | | 2026-11-19 | Оптимизация продукта (keep-alive REST, права раз на этап, параллельные чтения, сервисы WireGuard/scoped/IPsec) и шардированные тесты; A2 пройден на слое v28 (продукт `1e96ddac`) | +| 2026-11-21 | Инструкция по включению MCP: `mcp-enable-guide.md` | | 2026-11-21 | `server_remove` убирает свои profile и proposal (`d02a019b`, версия операции 3); `mmapp-test` на `mcp-d02a019b`, 5 из 5 прогонов IPsec подряд без остатка | | 2026-11-21 | Этап 3 закрыт: A6 и A7 приняты (5 повторов подряд), IPsec через MCP принят по D11 (5 из 5 на `a7d85fd0`) после трёх исправлений продукта: счётчики `/interface` (`28738785`), совместимость с RouterOS 7.24 (`e7eb108c`), ожидание глобальной блокировки (`a7d85fd0`). В этапе 3 открытых пунктов нет | diff --git a/docs/mcp-enable-guide.md b/docs/mcp-enable-guide.md new file mode 100644 index 00000000..51e12745 --- /dev/null +++ b/docs/mcp-enable-guide.md @@ -0,0 +1,316 @@ +# Включение MCP: наблюдение → подтверждения → ограниченная автономность + +Инструкция для администратора Manager. Она описывает, как дать внешнему AI-клиенту доступ через MCP в три шага, с проверкой на каждом шаге: + +1. Наблюдение: агент только читает. +2. Подтверждения: агент готовит изменения, человек одобряет каждое. +3. Ограниченная автономность: агент применяет изменения сам, в узкой области и в пределах лимитов. + +**По умолчанию всё выключено.** После установки: + +- MCP выключен; +- нет ни одного подключения; +- профили Route AI выключены, автоматическое восстановление маршрутов недоступно. + +Это закреплено тестом на свежей базе (`integration.test.ts`). + +Названия в кавычках «…» — надписи в интерфейсе, раздел **MCP** в Manager. + +## Перед началом + +### Права в портале + +| Право | Что даёт в разделе MCP | +| --- | --- | +| `mm:mcp:read` | открыть раздел, смотреть подключения, обращения, планы и операции; «Обновить мои права» для своего подключения; разрешить OAuth-доступ | +| `mm:mcp:approve` | «Подтвердить план» и «Отклонить». Нужны ещё права самой операции: например, для изменения сети — `mm:network:write` | +| `mm:mcp:pause` | «Остановить автоматические изменения» на вкладке «Обзор» | +| `mm:mcp:admin` | всё остальное: настройки, подключения, защиты, Route AI, OAuth-клиенты, сверка и восстановление | + +Подключению можно передать только те права, которые есть у его владельца. Иначе сохранение отклоняется: «Нельзя делегировать отсутствующие права». Менять политику подключения может только его владелец. + +### Настройки сервера + +- **`MCP_PUBLIC_URL`** — внешний адрес MCP, например `https://manager.example/mcp`. + - Путь — ровно `/mcp`, без query и без логина в адресе. + - Нужен HTTPS. HTTP допускается только для `localhost`, `127.0.0.1` и `[::1]`. + - При нарушении любого из правил MCP отвечает `INVALID_CONFIGURATION` (503). +- **`MCP_STATE_DIR`** — каталог ключей и поколения доступа. Храните его на постоянном томе. + - Если каталог потерян, при старте создаётся новое поколение. + - Тогда все выданные токены и все неприменённые планы перестают действовать. +- **Аудит.** Изменения начинаются только при доступном аудите, иначе вызов получает `AUDIT_UNAVAILABLE`. + +## Шаг 0. Разрешить обращения MCP + +1. «Настройки» → «Настройки MCP» → включите «Разрешить обращения MCP». +2. Там же задайте сроки хранения: + - «Хранение обращений, дней»: от 1 до 365, по умолчанию 30; + - «Хранение аудита, дней»: от 30 до 3650, по умолчанию 180. + +Пока флаг выключен: + +- любой токен получает `MCP_DISABLED` (503); +- воркер не запускает контроллер Route AI и не проверяет расхождения конфигурации. + +## Шаг 1. Наблюдение + +**Цель:** узнать, что агент читает и как часто, не давая ему ничего менять. + +### Создать подключение + +«Подключения» → «Выдать доступ». Откроется окно «Новое подключение». В нём: + +- **«Название»** — по нему подключение видно в журналах. +- **«Срок действия (UTC)»** — не больше года. Для первого шага достаточно нескольких дней. +- **«Режим управления»** — «Наблюдатель». Он же выбран по умолчанию. +- **Серверы и операции** — только те, что нужны агенту. + - Операция, не выданная подключению, получает `OPERATION_DENIED`. + - Сервер вне списка получает `SERVER_DENIED`. + - Глобальные операции работают только с «Разрешить выбранные глобальные операции». +- **Права** — только на чтение, например `mm:servers:read`. +- **Лимиты.** На этом шаге хватит значений по умолчанию: + + | Поле | По умолчанию | Отказ при превышении | + | --- | --- | --- | + | «Вызовов в минуту» | 60 | `RATE_LIMITED` | + | «Одновременных чтений» | 4 | `RATE_LIMITED` | + | «Изменений в час» | 10 | `BUDGET_EXCEEDED` | + | «Серверов на план» | 5 | `PLAN_LIMIT_EXCEEDED` | + | «Объектов на план» | 100 | `PLAN_LIMIT_EXCEEDED` | + +После сохранения появится «Одноразовый токен MCP». Он показывается один раз: + +1. Скопируйте токен в секреты AI-клиента. +2. Нажмите «Закрыть и скрыть токен». + +Токен действует до срока подключения. «Новый токен» выпускает замену, старый токен сразу перестаёт работать. + +### Подключить клиента + +Подходит любой MCP-клиент с транспортом Streamable HTTP. Настройки клиента: + +- адрес: `MCP_PUBLIC_URL`; +- заголовок: `Authorization: Bearer <токен>`. + +Формат настроек зависит от клиента. Держите токен в переменной окружения, а не в файле настроек. + +**Вход через OAuth вместо токена:** + +1. «Настройки» → «OAuth-клиенты»: зарегистрируйте клиента. В поле «Redirect URI, по одному на строку» укажите адреса точно. +2. При запросе доступа владелец видит «Разрешение OAuth-доступа» и выбирает подключение. +3. Клиент получает доступ ровно этого подключения, не шире. + +### Права владельца + +Подключение действует, пока подтверждены права его владельца. Подтверждение длится до истечения токена портала, с которым владелец подтвердил права, но не дольше 24 часов. Обновление сессии в портале этот срок не продлевает. Права подтверждаются: + +- при создании подключения; +- при сохранении «Изменить разрешения»; +- кнопкой «Обновить мои права». + +Когда срок прошёл, любой вызов получает `UNAUTHORIZED` (401): «Подключение недействительно или требуется подтверждение прав владельца». Помогает только «Обновить мои права». + +Если в портале отозвать сессии пользователя, Manager отзывает и его подключения MCP вместе с токенами и временными допусками. + +### Что агент может на этом шаге + +- **Может** вызывать операции чтения: каталоги, состояние, журналы. + - Диагностику `mm_server_terminal_diagnostic` (ping и подобное). Она требует права `mm:servers:write`, хотя ничего не меняет. + - Контрольные ping и traceroute пути `mm_route_path_verify`. +- **Не может** ничего менять. Все `*_plan`, включая нагрузочный тест полосы `mm_routing_measurement_plan`, получают `OBSERVER_WRITE_DENIED`. План при этом не создаётся. + +### Где смотреть + +- «Обзор»: вызовы за 24 часа, ошибки и отказы. +- «Обращения»: каждый вызов с результатом и причиной отказа. Есть фильтры по подключению, серверу и времени. +- «Подключения» → «Проверка подключения и временные допуски» → «Проверить готовность доступа». Это проверочное чтение возможностей от имени подключения. + +### Когда переходить к шагу 2 + +- Вы знаете, какие операции и серверы нужны агенту. +- На вкладке «Обращения» нет неожиданных отказов `OPERATION_DENIED`, `SERVER_DENIED` и `RATE_LIMITED`. + +## Шаг 2. Подтверждения + +**Цель:** агент готовит изменения, а человек видит каждое до записи на роутер. + +### Перевести подключение + +«Подключения» → подключение → «Изменить разрешения»: + +- **«Режим управления»** — «С подтверждением». +- **Операции записи** — добавьте нужные `*_plan`. +- **Права** — добавьте права записи. +- **«Изменений в час».** Бюджет считает изменяемые объекты, а не вызовы. + - План, который не помещается в остаток бюджета, отклоняется до подтверждения с `BUDGET_EXCEEDED`. + - Пример: удаление сервера IPsec на стенде меняет 11 объектов, при значении 10 оно не пройдёт никогда. + - Ставьте значение не меньше самого большого ожидаемого плана, умноженного на число таких планов в час. + +Сохранение не меняет токен. Оно увеличивает версию политики и аннулирует все неприменённые планы подключения. Возврат на шаг 1 делается так же: сменить режим на «Наблюдатель». + +### Как проходит изменение + +1. Агент вызывает `*_plan`. Manager читает роутер, строит план и проверяет политику. +2. План получает состояние `awaiting-approval`. Он виден в «Планы и операции» → «Планы изменений», а на вкладке «Обзор» растёт счётчик «Ожидают подтверждения». +3. Человек с `mm:mcp:approve` открывает план, проверяет изменения и нажимает «Подтвердить план» или «Отклонить». Подтверждение относится ровно к показанному плану. +4. Агент вызывает `mm_change_apply` с ID плана. Применить план может и человек: «Применить план». +5. Ход записи — в «Выполнение операций»: «Записано намерение», «Применена», «Результат проверен». Агент читает то же через `mm_operation_get`. + +**У плана есть срок:** + +- 5 минут для сетевых операций; +- 15 минут для остальных; +- для `servers.poll` и `routing.community.switch` — меньше, если раньше истекают данные, на которых построен план. + +Истёкший план не применяется: «Срок плана истёк. Подготовьте новый план». + +Переключение постоянного профиля Route AI подтверждает только владелец подключения. + +### Защита объектов + +«Разрешения» → «Защищённые объекты» → «Добавить защиту». Варианты: + +- **«Запрет изменений»** — любой план, который затрагивает объект, отклоняется с `PROTECTED_OBJECT`. +- **«Подтверждение человеком»** — такой план требует подтверждения в любом режиме, в том числе в автономном. + +Защита не ограничивает чтение. + +Ставьте защиту до перехода к шагу 3, в первую очередь: + +- на интерфейсы и адреса, через которые Manager управляет роутером; +- на маршруты к нему. + +«Проверка разрешений» на той же вкладке показывает решение политики для операции и объекта без выполнения. + +### Если результат не тот + +«Планы и операции» → «Сверка и восстановление»: + +1. Укажите UUID операции и нажмите «Сверить состояние операции». Manager прочитает роутер. +2. «Подготовить обратный план» создаёт отдельный план возврата. Он проходит те же проверки и подтверждение. Если объект после операции изменили извне, Manager откажет. + +### Когда переходить к шагу 3 + +- Планы агента совпадают с тем, что вы ожидали. +- Отклонённых планов нет или почти нет. +- Операции доходят до «Результат проверен». +- «Расхождения конфигурации» пусты. +- Защиты стоят на всём, что агент менять не должен. + +## Шаг 3. Ограниченная автономность + +**Цель:** агент применяет повторяющиеся изменения сам, в узкой области. + +### Перевести подключение + +«Изменить разрешения» → «Режим управления» → «Автономный». Сразу сузьте остальное: + +- **серверы и операции** — только те, что агент применял на шаге 2; +- **«Срок действия (UTC)»** — короткий; +- **«Изменений в час»** и «Объектов на план» — по фактическому размеру планов шага 2, без лишнего запаса; +- **«Опасные действия»** — оставьте «Всегда подтверждать». + - «Автономно для явно выбранных действий» снимает подтверждение только с отмеченных опасных операций. + - Какие операции опасные, видно в каталоге операций и в панели «Проверка разрешений». + +### Что по-прежнему требует человека + +План без подтверждения не применяется. Подтверждение остаётся обязательным: + +- для объектов с защитой «Подтверждение человеком». «Запрет изменений» по-прежнему запрещает; +- для опасных операций, кроме явно выбранных; +- для операций, которые сами требуют человека: Manager помечает весь сервер или операцию защитой «Подтверждение человеком». Такой план остаётся в состоянии `awaiting-approval`. + +### Временный допуск + +«Подключения» → «Проверка подключения и временные допуски» → «Выдать временный допуск». Допуск: + +- получает отдельный токен; +- только сужает основной доступ: серверы, операции, глобальные действия; +- действует не дольше 24 часов («Срок допуска, минут»); +- снимается кнопкой «Отозвать допуск». + +Удобно для разовой автономной работы: основное подключение остаётся в «С подтверждением», автономный режим — только у узкого допуска. + +### Срок работы без человека + +Автономная работа ограничена правами владельца: до истечения токена портала, с которым он последний раз подтвердил права, и не дольше 24 часов после этого. Дольше агент без человека не работает. Это намеренно. + +## Постоянный контроллер Route AI + +Отдельная функция: контроллер сам переключает маршруты по профилю. + +«Route AI» → «Постоянный контроллер Route AI» → «Создать профиль». + +**Требования к подключению:** + +- режим не «Наблюдатель»; +- у владельца и у подключения есть `mm:network:read`, `mm:network:write` и `mm:filters:write`; +- серверы профиля входят в область подключения. + +**Требования к допуску:** + +- «Допуск действует до (UTC, максимум 24 часа)»; +- срок не позже срока токена, подключения и прав владельца. + +**Профиль отдельной таблицы или VRF:** + +- нужна явная BGP-привязка; +- у каждого пути — контрольная проба с исходным адресом. + +**Автоматическое восстановление недоступно.** Профиль с ним отклоняется: `ROUTE_RECOVERY_EXECUTOR_UNAVAILABLE`. Нет источника событий RouterOS, который замечает пропуски. + +**Контроллер останавливается сам:** + +- когда истёк допуск; +- при «Обновить мои права» владельца подключения; +- при обнаружении расхождения конфигурации у операций этого подключения; +- при «Остановить автоматические изменения». + +Пока MCP выключен, контроллер не работает. + +Проверить путь вручную, без переключения: «Контрольная проверка пути». + +## Остановить, приостановить, отозвать + +| Действие | Где | Что происходит | Обратимо | +| --- | --- | --- | --- | +| «Пауза» | «Подключения» | Токены подключения не принимаются, неприменённые планы аннулируются | да, «Включить» | +| «Отозвать» | «Подключения» | Подключение и все его токены отозваны, неприменённые планы аннулируются | нет: `CONNECTION_REVOKED` | +| «Новый токен» | «Подключения» | Старый токен перестаёт работать | — | +| «Отозвать допуск» | «Проверка подключения и временные допуски» | Временный допуск и его токен перестают действовать | нет | +| Снять «Разрешить обращения MCP» | «Настройки» | Все вызовы получают `MCP_DISABLED`, контроллер и проверка расхождений не работают. Токены не отзываются | да: после включения токены снова работают | +| «Остановить автоматические изменения» | «Обзор», право `mm:mcp:pause` | MCP выключается, все профили Route AI выключаются. Начатые записи завершаются или сверяются | частично: MCP включается флагом, профили Route AI включают заново вручную | +| «Отключить и отозвать токены» | «Настройки» → «OAuth-клиенты» | OAuth-клиент отключён, его токены отозваны | нет | + +После работы с агентом, которому доступ больше не нужен, — «Отозвать», а не «Пауза». + +## Частые отказы + +| Код | Причина | Что делать | +| --- | --- | --- | +| `MCP_DISABLED` | MCP выключен | «Разрешить обращения MCP» | +| `UNAUTHORIZED` | Токен неверный, отозван или истёк, подключение на паузе, права владельца не подтверждены или сменилось поколение доступа | проверить подключение, «Обновить мои права», при необходимости «Новый токен» | +| `OPERATION_DENIED` | Операция не выдана подключению | добавить операцию в «Изменить разрешения» | +| `OWNER_PERMISSION_MISSING`, `CONNECTION_PERMISSION_MISSING` | Нет права у владельца или у подключения | выдать право в портале или подключению | +| `SERVER_DENIED`, `GLOBAL_DENIED` | Сервер вне области, глобальные операции не разрешены | расширить область, если это нужно | +| `GRANT_INACTIVE`, `GRANT_SCOPE_DENIED` | Временный допуск истёк или запрос шире допуска | новый допуск | +| `RATE_LIMITED` | Минутный лимит вызовов или одновременных чтений | поднять лимит или замедлить клиента | +| `OBSERVER_WRITE_DENIED` | Изменение в режиме «Наблюдатель» | перейти на шаг 2 | +| `BUDGET_EXCEEDED` | План не помещается в часовой бюджет изменений | подождать или поднять «Изменений в час» | +| `PLAN_LIMIT_EXCEEDED` | Слишком много серверов или объектов в плане | разбить план или поднять лимит | +| `PROTECTED_OBJECT` | Объект под «Запрет изменений» | снять защиту, если изменение действительно нужно | +| `AUDIT_UNAVAILABLE` | Аудит недоступен | восстановить базу или аудит; изменения до этого не выполняются | +| `PLAN_EXPIRED` | Истёк срок плана или исходных данных | подготовить новый план | +| `CONFIGURATION_BUSY` | Глобальная конфигурация занята другой операцией дольше 30 секунд | повторить позже | + +## Что проверено + +Доказательства и статусы по каждому критерию — в [mcp-final-manifest.md](mcp-final-manifest.md). + +- **Режим «С подтверждением» проверен на стенде.** + - IPsec: пять прогонов подряд, в каждом 4 подтверждения в интерфейсе. Применение без подтверждения отклонено. + - Маршрутизация A3: 2 подтверждения. + - Выдача токена в интерфейсе, подтверждение плана и подписанный отзыв в настоящих Manager и Portal — EXT-1. +- **Режимы «Наблюдатель» и «Автономный», защиты, бюджет и лимиты** покрыты тестами политики (`policy.test.ts`). На стенде отдельно не проверялись. +- **Раздел MCP в интерфейсе** проверен частично: выдача ограниченного доступа, отказы, фильтры и пагинация на стенде не проверялись (UI-1). +- **Автоматическое восстановление маршрутов** не реализовано и выключено (этап 4 плана завершения). diff --git a/docs/mcp-final-manifest.md b/docs/mcp-final-manifest.md index 2981c317..c8782c7c 100644 --- a/docs/mcp-final-manifest.md +++ b/docs/mcp-final-manifest.md @@ -91,7 +91,7 @@ | --- | --- | --- | | Итоговый снимок исходников и регрессия | Этап 1 на прежнем HEAD; на коде `d02a019b`: шардированный `test-mcp-postgres-sharded.mjs` 6 из 6, `--module-completion`, набор A7 205/205 | принято частично: полный этап 1 (`lint`, `build`, `test:mcp:pg:all`, Playwright) на итоговом HEAD повторяется перед PR | | Контракты, безопасность, покрытие, судьба нерешённой истории | `coverage.test.ts` (этап 1); этот манифест | принято частично: манифест составлен, решение по открытым строкам — за владельцем | -| Инструкции по эксплуатации и безопасное включение | Проверка «выключено по умолчанию» (выше); инструкция по включению — этап 5 | открыто | +| Инструкции по эксплуатации и безопасное включение | Проверка «выключено по умолчанию» (выше); [mcp-enable-guide.md](mcp-enable-guide.md) — три шага включения, остановка и отзыв, частые отказы | принято частично: на стенде проверен только режим «С подтверждением»; «Наблюдатель» и «Автономный» — тестами политики. Сокращение `docs/mcp.md` до пользовательской документации — этап 5 | ## История отказов (не перекрашивается) @@ -116,4 +116,4 @@ - `mmapp-test`: backend `mcp-d02a019b`, frontend `mcp-29998815`; MCP выключен, подключения отозваны, тестовая учётная запись `a3-agent` отключена. - Оба CHR: после IPsec `ipv4/ipv6-fast-path-active=false` при неизменной конфигурации; причина и способ возврата не установлены. - VPS: 16 резервных копий `/root/backups/*pre-*`, 9 тегов `mmapp-test/backend`, каталоги `/root/c2c4-29998815` и `/var/tmp/restore58-*` — чистка по решению владельца. -- Этап 4: PATHS, RAM-1, autoRecovery, RT-3. Этап 5: инструкция по включению, сокращение `docs/mcp.md`, PR в `main`, три продуктовые задачи. +- Этап 4: PATHS, RAM-1, autoRecovery, RT-3. Этап 5: сокращение `docs/mcp.md`, PR в `main`, три продуктовые задачи.