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

docs/tools.md

@@ -0,0 +1,80 @@
+# Справочник инструментов
+
+36 инструментов, сгруппированы по фазам. Общие аргументы:
+
+- `server` — алиас стенда из конфига (по умолчанию `default`). Необязателен.
+- `app_id` — идентификатор сервиса (см. `list_applications`).
+- `confirm` — `true` для разрушительных операций.
+
+Обозначения: **R** — только чтение; **W** — изменяет; **W!** — изменяет и
+требует `confirm="true"`.
+
+## Наблюдение (observe)
+
+| Инструмент | Тип | Аргументы | Что делает |
+|---|---|---|---|
+| `server_health` | R | — | Живость `config_server` (`GET /health`). |
+| `whoami` | R | — | Кто авторизован. |
+| `server_info` | R | — | Версия API (capability-probe), адрес, режим `read_only`. Вызывать первым. |
+| `list_applications` | R | `include_presence` | Список сервисов с хостами и статусами. |
+| `get_application` | R | `app_id` | Детали: compose, версии, env-файлы, журнал миграций. |
+| `get_config` | R | `app_id` | Текущие compose и env сервиса. |
+| `env_files` | R | `app_id` | Имена текущих env-файлов. |
+| `compose_version` | R | `version_id` | Содержимое версии compose. |
+| `env_version` | R | `version_id` | Содержимое версии env-файла. |
+| `env_versions` | R | `app_id`, `filename` | Все версии конкретного env-файла. |
+| `list_tasks` | R | `host_ip`, `status`, `task_type`, `limit` | Задачи агентов (аудит, поиск failed). |
+| `get_task` | R | `task_id`, `wait`, `tail`, `output_bytes` | Статус/вывод задачи; `wait=true` ждёт завершения. |
+| `get_deployment_files` | R | — | schema, manifest, prebuild_vars, ip_overrides. |
+| `ip_match` | R | — | Сопоставление IP схемы и агентов. |
+| `release_job` | R | — | Статус фоновой выгрузки релиза. |
+| `deployment_tasks` | R | — | Последние release-задачи (sync/start). |
+| `stats` | R | — | Счётчики версий compose/env и логов миграций. |
+| `service_map` | R | — | Карта хостов и сервисов. |
+| `overview` | R | — | Сводка: health, stats, сервисы не в OK, failed-задачи. |
+| `release_status` | R | — | Сводка развёртывания: job, задачи, приложения, IP. |
+
+## Конфигурация (configure)
+
+| Инструмент | Тип | Аргументы | Что делает |
+|---|---|---|---|
+| `set_compose` | W | `app_id`, `content` | Задать compose, создать версию, отправить агенту. |
+| `set_env` | W | `app_id`, `filename`, `content` | Задать env-файл, создать версию, отправить агенту. |
+| `restore_compose` | W! | `version_id`, `confirm` | Восстановить версию compose. |
+| `restore_env_version` | W! | `version_id`, `confirm` | Восстановить версию env-файла. |
+| `update_config` | W | `app_id` | Повторно отправить текущий конфиг агенту. |
+
+## Жизненный цикл (operate)
+
+| Инструмент | Тип | Аргументы | Что делает |
+|---|---|---|---|
+| `deploy` | W | `app_id`, `wait` | `docker-compose up -d`. |
+| `restart` | W | `app_id`, `wait` | `down` + `up -d`. |
+| `down` | W! | `app_id`, `confirm`, `wait` | `docker-compose down`. |
+| `migrate` | W | `app_id`, `wait` | `docker-compose run migration`. |
+| `update_front` | W! | `app_id`, `build_dir`, `confirm` | Загрузить сборку фронта (каталог внутри `front_roots`). |
+
+## Развёртывание релиза (release)
+
+| Инструмент | Тип | Аргументы | Что делает |
+|---|---|---|---|
+| `save_deployment_files` | W | `schema`, `manifest`, `prebuild_vars`, `ip_overrides` | Сохранить файлы развёртывания (только переданные поля). |
+| `seed_hosts` | W | — | Создать хосты из schema.json. |
+| `fill_vars` | W | — | Заполнить prebuild_vars из схемы. |
+| `download_release` | W! | `load_images`, `gitlab_token`, `confirm` | Выгрузить релиз; `load_images=true` — фон. |
+| `start_services` | W | — | Создать задачи запуска сервисов по схеме. |
+
+## Обслуживание (maintain)
+
+| Инструмент | Тип | Аргументы | Что делает |
+|---|---|---|---|
+| `cleanup_old_versions` | W! | `days`, `confirm` | Удалить версии/логи старше N дней. |
+
+## Результаты и ошибки
+
+- Успех — читаемый JSON.
+- **Доменная ошибка** (неверный `app_id`, нет confirm, отказ сервера) возвращается
+  как результат инструмента с текстом — ассистент видит её и может исправить.
+- **Инфраструктурная ошибка** (нет сети) — как ошибка протокола.
+- Длинный вывод задачи обрезается (по умолчанию с сохранением хвоста — там
+  обычно причина сбоя); `get_task` принимает `output_bytes` и `tail`.