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]>
This commit is contained in:
1 parent
c1abfffe26
commit
d586f87009
4 files changed
+19
-6
No files matched your search
@@ -119,7 +119,7 @@
|
||||
- [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`)
|
||||
- [x] Сократить `docs/mcp.md` (417 КБ) до пользовательской документации — 2026-11-21: прежний файл перенесён без изменений текста в [mcp-implementation-history.md](mcp-implementation-history.md) с пометкой «исторический»; новый [mcp.md](mcp.md) (19 КБ): настройка сервера, подключение клиента (HTTP, stdio, OAuth), путь изменения, возможности по областям, Route AI, webhook отзыва порталом, восстановление базы, ограничения, проверки. Каждое утверждение написано по коду или манифесту, старый текст служил только списком тем: в нём были устаревшие места (автовосстановление «включается человеком», восстановление ревизий WireGuard и IPsec «pending», отправка отзыва из портала «не принята»). Режимы, лимиты и коды отказов не повторяются — ссылка на `mcp-enable-guide.md`. Входящие ссылки обновлены (README, план реализации, аудит трафика), хеши `documentHashes` в JSON-доказательствах оставлены как исторические
|
||||
- [x] Сократить `docs/mcp.md` (417 КБ) до пользовательской документации — 2026-11-21: прежний файл перенесён без изменений текста в [mcp-implementation-history.md](mcp-implementation-history.md) с пометкой «исторический»; новый [mcp.md](mcp.md) (19 КБ): настройка сервера, подключение клиента (HTTP, stdio, OAuth), путь изменения, возможности по областям, Route AI, webhook отзыва порталом, восстановление базы, ограничения, проверки. Настройка, OAuth, webhook, восстановление базы, числа, имена инструментов и переменных проверены по коду; описания гарантий исполнения и тестовых наборов взяты из прежнего текста и сверены выборочно. В прежнем тексте были устаревшие места (автовосстановление «включается человеком», восстановление ревизий WireGuard и IPsec «pending», отправка отзыва из портала «не принята»). Режимы, лимиты и коды отказов не повторяются — ссылка на `mcp-enable-guide.md`. Входящие ссылки обновлены (README, план реализации, аудит трафика), хеши `documentHashes` в JSON-доказательствах оставлены как исторические. Найдено при проверке: поставляемый deploy не открывает `/mcp`, `/oauth/*` и `/.well-known/*` на backend (frontend проксирует только `/api` и `/health`, `/mcp` — страница интерфейса); стенд подключался к backend через туннель. Записано в `mcp.md` как ограничение
|
||||
- [ ] PR в `main`
|
||||
Продуктовые задачи из анализа таймингов (2026-11-17), не блокируют слияние в `main`; детали и числа в `mcp-stand-run-a-plan.md`, раздел «Вопросы к продукту»:
|
||||
|
||||
|
||||
@@ -116,4 +116,5 @@
|
||||
- `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-*` — чистка по решению владельца.
|
||||
- Публичный маршрут MCP: поставляемые `deploy/docker-compose*.yml` не передают backend `/mcp`, `/oauth/*` и `/.well-known/*` (frontend проксирует только `/api` и `/health`, `/mcp` — страница интерфейса). Стенд подключался к backend через туннель, публичный путь не проверялся. Решить: добавить маршрут на отдельный хост в deploy или оставить ручной настройкой (описано в `mcp.md`)
|
||||
- Этап 4: PATHS, RAM-1, autoRecovery, RT-3. Этап 5: PR в `main`, три продуктовые задачи.
|
||||
@@ -1,6 +1,6 @@
|
||||
# MCP: подключение и состояние реализации
|
||||
|
||||
> **Исторический документ.** До 2026-11-21 это был `docs/mcp.md`: инженерные записи о ходе реализации MCP. Часть утверждений устарела. Пользовательская документация — [mcp.md](mcp.md), включение — [mcp-enable-guide.md](mcp-enable-guide.md), статусы и доказательства — [mcp-final-manifest.md](mcp-final-manifest.md). Хеши `documentHashes["docs/mcp.md"]` в JSON-доказательствах относятся к прежним версиям этого файла.
|
||||
> **Исторический документ.** До 2026-11-21 это был `docs/mcp.md`: инженерные записи о ходе реализации MCP. Часть утверждений устарела. Пользовательская документация — [mcp.md](mcp.md), включение — [mcp-enable-guide.md](mcp-enable-guide.md), статусы и доказательства — [mcp-final-manifest.md](mcp-final-manifest.md). Хеши `documentHashes["docs/mcp.md"]` в JSON-доказательствах относятся к прежним версиям этого файла: они в истории Git под старым путём, `git log -- docs/mcp.md`.
|
||||
|
||||
В текущем каталоге 368 инструментов. Сверка реестра с Fastify подтвердила 265 REST-маршрутов, из них 202 сопоставлены инструментам MCP и 63 относятся к инфраструктуре. Незарегистрированных маршрутов и адаптеров со статусом `pending` нет. Двухузловая приёмка переключения с проверкой трафика и замер всей установки в пределах 2 ГБ остаются открыты. [План](mcp-implementation-plan.md) · [Текущий статус](mcp-current-progress.json).
|
||||
|
||||
|
||||
+16
-4
@@ -28,7 +28,17 @@ Manager работает как MCP-сервер. Внешний AI-клиент
|
||||
- несколько процессов backend должны видеть одно и то же состояние;
|
||||
- при потере каталога все токены, неприменённые планы и зашифрованные данные MCP становятся недоступны.
|
||||
|
||||
**Reverse proxy** должен сохранять заголовок `Host` и пропускать `/mcp`, `/oauth/*` и `/.well-known/*`.
|
||||
**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.
|
||||
|
||||
@@ -71,7 +81,8 @@ npm --prefix backend run mcp:stdio
|
||||
- access token живёт до 15 минут и не дольше подключения;
|
||||
- refresh token — до 30 дней, меняется при каждом обновлении;
|
||||
- повторное использование старого refresh token отзывает всю цепочку;
|
||||
- динамической регистрации клиентов нет.
|
||||
- динамической регистрации клиентов нет;
|
||||
- OAuth-токены, как и обычный токен, работают только пока действуют права владельца подключения: не дольше 24 часов после их подтверждения, см. [инструкцию](mcp-enable-guide.md#права-владельца). Refresh token этот срок не продлевает.
|
||||
|
||||
## Как проходит изменение
|
||||
|
||||
@@ -95,7 +106,7 @@ npm --prefix backend run mcp:stdio
|
||||
|
||||
- `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`.
|
||||
- Универсального отката удалений и сервисных операций нет. Для них есть восстановление ревизий: `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`.
|
||||
|
||||
В интерфейсе то же — «Планы и операции» → «Сверка и восстановление».
|
||||
|
||||
@@ -188,6 +199,7 @@ npm --prefix backend run mcp:stdio
|
||||
|
||||
**Известные недостатки:**
|
||||
|
||||
- **Публичный маршрут MCP в поставляемом deploy.** Его нет, настраивается вручную: см. раздел о настройке сервера выше.
|
||||
- **VRF поверх активного GRE.** Создание может закончиться «Выполнена частично», хотя VRF на роутере создан. Проверяйте сверкой.
|
||||
- **Лимит памяти 2 ГиБ** для всей установки не подтверждён.
|
||||
|
||||
@@ -224,4 +236,4 @@ npm --prefix backend run build
|
||||
- `:pg:all` добавляет профили backend.
|
||||
- `:pg:sharded` даёт то же покрытие, что `test:mcp:pg`, но медленные проверки идут параллельными шардами.
|
||||
|
||||
Для проверки восстановления нужны `pg_dump` и `pg_restore` PostgreSQL 18: в `PATH` или в каталоге из `MMAPP_PG_CLIENT_BIN`. Встроенный PostgreSQL для Windows этих утилит не содержит.
|
||||
Наборам `test:mcp:pg*` нужны `pg_dump` и `pg_restore` PostgreSQL 18: в `PATH` или в каталоге из `MMAPP_PG_CLIENT_BIN`. Без них основной набор падает с `DATABASE_DUMP_TOOL_UNAVAILABLE`. Встроенный PostgreSQL для Windows этих утилит не содержит.
|
||||
Reference in new issue
Block a user