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,82 @@
+# Эксплуатация
+
+`omnichannel-mcp` работает в **плоскости управления**: он видит статусы,
+конфигурацию, задачи и историю, но не заглядывает внутрь контейнеров. Это
+разделение осознанное — так сервер остаётся безопасным и предсказуемым.
+
+## Что можно, а что нет
+
+| Задача | Инструменты этого сервера | Вне него |
+|---|---|---|
+| Статусы сервисов и хостов | `overview`, `list_applications`, `service_map` | — |
+| Аудит и разбор задач | `list_tasks`, `get_task`, `deployment_tasks` | — |
+| Конфигурация compose/env, версии, откат | `get_application`, `get_config`, `env_files`, `compose_version`, `env_versions`, `restore_compose`, `restore_env_version` | — |
+| Жизненный цикл сервиса | `deploy`, `restart`, `down`, `migrate` | — |
+| Развёртывание релиза | `save_deployment_files`, `seed_hosts`, `fill_vars`, `download_release`, `release_job`, `start_services` | — |
+| **Логи контейнеров** | — | отдельный MCP-сервер SSH/`docker logs` |
+| **Ресурсы (CPU/RAM/диск)** | — | мониторинг (SSH, Zabbix, Prometheus) |
+| **Данные в БД** | — | отдельный MCP-сервер для БД |
+| **HTTP-проверки сервисов** | — | отдельный MCP-сервер для HTTP/веб |
+
+Иными словами: этим сервером удобно отвечать на «что и с какой конфигурацией
+развёрнуто и что сломалось при деплое», а диагностику рантайма подключайте
+дополнительными MCP-серверами.
+
+## Типовые сценарии
+
+### «Что сейчас на стенде?»
+
+> «Покажи сводку по стенду prod.»
+
+`overview` вернёт health, статистику, сервисы не в статусе OK и последние
+упавшие задачи — это самый быстрый «снимок».
+
+### «Почему упал деплой?»
+
+1. `list_tasks {status:"failed", limit:20}` — найти задачу.
+2. `get_task {task_id}` — прочитать `output` (stdout/stderr). По умолчанию
+   оставляется **хвост** вывода, где обычно и причина; при необходимости
+   увеличить `output_bytes`.
+3. При необходимости сравнить конфиг: `get_application {app_id}`.
+
+### «Сервис не поднялся / зависает»
+
+1. `get_application {app_id}` — статус, текущий compose/env, журнал миграций.
+2. `list_tasks {host_ip, task_type}` — история операций по хосту.
+3. Повторить контролируемо: `restart {app_id, wait:true}` и снова `get_task`.
+4. Если внутри сервиса — переключиться на SSH-инструменты (логи).
+
+### «Нужно поправить конфигурацию»
+
+1. `get_config {app_id}` / `get_application {app_id}` — текущее.
+2. `set_env` / `set_compose` — изменить (создаётся версия).
+3. `deploy` или `restart` — применить на хосте.
+4. Проверить `get_task`/`overview`. При неудаче — откат (`restore_*`).
+
+### «Проверить релиз»
+
+- `release_job` — статус фоновой выгрузки (фаза, прогресс образов).
+- `deployment_tasks` — последние sync/start-задачи.
+- `ip_match` — корректно ли сопоставлены хосты и агенты.
+
+### «Обслуживание»
+
+- `stats` — сколько версий и логов накопилось.
+- `cleanup_old_versions {days:180, confirm:true}` — удалить устаревшие версии
+  (текущие не трогаются).
+
+## Полезные фильтры
+
+- `list_tasks` ограничивает выборку (`limit` ≤ 500) и фильтрует по `host_ip`,
+  `status`, `task_type`.
+- `list_applications {include_presence:true}` включает служебные записи хостов
+  (хост без развёрнутых сервисов).
+
+## Ограничения и защита
+
+- Длинные выводы обрезаются (`max_output_bytes`), чтобы не переполнить контекст
+  ассистента.
+- Ожидание задач (`wait`) ограничено `task_poll_max_sec`; если задача не успела —
+  вернётся её текущее состояние, а не ошибка.
+- Мутации сериализуются на сервер (`max_concurrent_mutations`) — параллельные
+  `restart` не наложатся друг на друга.