Initial commit: omnichannel-mcp — MCP-сервер управления платформой Omnichannel

2026-10-07 20:13:23 +07:00
commit fdbd4a4fb6
54 changed files with 5672 additions and 0 deletions
@@ -0,0 +1,132 @@
+# Развёртывание
+
+Два пути: **быстрый** (для уже зарегистрированного сервиса — изменить compose/env
+и поднять) и **полный релиз** (схема + манифест → выгрузка релиза → запуск на
+одном или нескольких серверах).
+
+> Перед изменяющими операциями убедитесь, что `read_only=false` в конфиге, а
+> ассистент запрашивает подтверждение (`confirm`) на разрушительные шаги.
+
+## Быстрый путь: один уже известный сервис
+
+```text
+Промпт: «Обнови compose сервиса demo_web на образ nginx:1.27, подними его и дождись результата.»
+```
+
+Вызовы:
+
+1. `list_applications` — найти `demo_web` и его `app_id` (или `get_application`, если id известен).
+2. `set_compose {app_id, content}` — записать новый compose (создаётся версия, конфиг уходит агенту).
+   При необходимости — `set_env {app_id, filename, content}`.
+3. `deploy {app_id, wait:true}` — `docker-compose up -d` и ожидание задачи.
+4. `overview` — убедиться, что сервис поднялся.
+
+Для перезапуска — `restart`; для остановки — `down {confirm:true}`.
+
+## Полный релиз: один сервер
+
+Минимальная схема — один хост:
+
+```json
+{
+  "vm1": { "ip": "10.20.30.11", "services": ["user_system_front"] }
+}
+```
+
+```text
+Промпт: «Сохрани schema.json и manifest.json, разложи хост, скачай релиз с образами,
+дождись завершения и запусти сервисы.»
+```
+
+1. `save_deployment_files {schema, manifest}`
+2. `ip_match` — проверить, что IP хоста сопоставлен агенту.
+3. `seed_hosts` — создать запись хоста до выхода агента.
+4. `download_release {load_images:true, confirm:true}` → `{"status":"started"}`
+5. `release_job` (опрос) — `status: running` → `completed`
+6. `start_services` → `start_task_ids`
+7. `deployment_tasks` / `get_task {task_id, wait:true}` — результат запуска
+8. `overview` — сводка
+
+## Полный релиз: несколько серверов
+
+Схема описывает все VM и их сервисы:
+
+```json
+{
+  "vm-node-1": { "ip": "10.20.30.11", "services": ["chats", "user_system"] },
+  "vm-node-2": { "ip": "10.20.30.12", "services": ["report_system"] }
+}
+```
+
+Манифест сопоставляет сервис и пакет релиза (URL архива в GitLab):
+
+```json
+{
+  "services": {
+    "chats":         { "package": "https://gitlab.example/api/v4/.../chats.tar.gz" },
+    "user_system":   { "package": "https://gitlab.example/api/v4/.../user_system.tar.gz" },
+    "report_system": { "package": "https://gitlab.example/api/v4/.../report_system.tar.gz" }
+  }
+}
+```
+
+Порядок:
+
+1. `save_deployment_files {schema, manifest}` (при необходимости — `prebuild_vars`).
+2. `ip_match` — увидеть `matched_pairs` и `unmatched_schema_ips`.
+   Если IP в схеме не совпадают с IP агентов — задать соответствие через
+   `save_deployment_files {ip_overrides}`:
+   ```json
+   { "10.20.30.11": "10.20.30.101", "10.20.30.12": "10.20.30.102" }
+   ```
+   затем снова `ip_match`.
+3. `fill_vars` (опционально) — заполнить `prebuild_vars` из схемы.
+4. `seed_hosts` — создать записи хостов.
+5. `download_release {load_images:true, confirm:true}` — запускает фоновую
+   выгрузку пакетов и образов; прогресс — `release_job`
+   (`phase`, `images_pulled`/`images_total`).
+   Без образов: `download_release {load_images:false}` вернёт
+   `downloaded_services` и `sync_task_ids`.
+6. `start_services` → `start_task_ids` (по одной задаче на хост).
+7. `deployment_tasks` и `get_task {wait:true}` — дождаться результата по каждому хосту.
+8. `overview` — итоговая сводка; `list_applications` — статусы сервисов.
+
+> Токен GitLab: задайте `gitlab_token` в конфиге сервера (или переменной
+> окружения) — тогда не придётся передавать секрет в аргументе.
+
+## Обновление фронта
+
+Фронт-сервисы (`user_system_front`, `chat_widget`, `scenario_front` и др.)
+принимают собранную папку.
+
+1. В конфиге сервера задайте `front_roots` — каталог, куда вы кладёте сборки:
+   ```json
+   "front_roots": ["/srv/omni-front-builds"]
+   ```
+2. ```text
+   Промпт: «Обнови фронт user_system_front из /srv/omni-front-builds/us.»
+   ```
+   `update_front {app_id, build_dir:"/srv/omni-front-builds/us", confirm:true}` →
+   задача агенту → `get_task {wait:true}`.
+
+Каталог обязан лежать внутри `front_roots` (защита от загрузки произвольных
+путей); содержимое `build_folder` на хосте заменяется целиком.
+
+## Откат конфигурации
+
+Каждое изменение compose/env создаёт версию, поэтому откат безопасен.
+
+- Compose: `get_application {app_id}` → выбрать `version_id` → `restore_compose {version_id, confirm:true}`.
+- Env: `env_versions {app_id, filename}` → `restore_env_version {version_id, confirm:true}`.
+
+Восстановление создаёт **новую** версию (история сохраняется) и отправляет
+конфиг агенту.
+
+## Миграции
+
+```text
+Промпт: «Запусти миграции сервиса 5 и проверь результат.»
+```
+
+`migrate {app_id:5, wait:true}`; журнал последних миграций — в
+`get_application` (`migration_logs`).