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,153 @@
+# Конфигурация
+
+Конфиг — JSON-файл (по умолчанию `config.json`), который задаёт подключения к
+`config_server` и политику безопасности. Рядом можно положить
+`config.local.json` с секретами — он накладывается поверх и не коммитится.
+
+## Как задать путь к конфигу
+
+Приоритет (первый найденный):
+
+1. аргумент инструмента `config_path` (для обёрток; обычно не нужен);
+2. флаг запуска `-config /path/config.json`;
+3. каталог из переменной окружения `OMNI_CONFIG_DIR` (в нём берётся
+   `omnichannel-mcp.json`).
+
+Обычный режим — флаг `-config`.
+
+## Структура
+
+```json
+{
+  "servers": [ { … }, { … } ],
+  "default": "prod",
+  "read_only": true,
+  "allow_hosts": ["10.20.30.40"]
+}
+```
+
+| Поле | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `servers` | массив | — | Подключения к стендам. Обязательно, если не задан shorthand. |
+| `default` | строка | первый сервер | Алиас сервера, если в вызове не указан `server`. |
+| `read_only` | bool | `true` | Запрещает изменяющие инструменты (безопасный режим). |
+| `allow_hosts` | массив | пусто | Если задан — `base_url` любого сервера обязан быть на этих хостах. |
+
+### Поля сервера
+
+```json
+{
+  "alias": "prod",
+  "base_url": "http://10.20.30.40:5005",
+  "username": "${OMNI_USER}",
+  "password": "${OMNI_PASSWORD}",
+  "readonly_username": "${OMNI_RO_USER}",
+  "readonly_password": "${OMNI_RO_PASSWORD}",
+  "gitlab_token": "${OMNI_GITLAB_TOKEN}",
+  "insecure_skip_verify": false,
+  "front_roots": ["/srv/omni-front-builds"],
+  "timeout_sec": 30,
+  "upload_timeout_sec": 300,
+  "task_poll_max_sec": 120,
+  "task_poll_interval_sec": 2,
+  "max_output_bytes": 100000,
+  "max_upload_bytes": 536870912,
+  "max_concurrent_mutations": 1
+}
+```
+
+| Поле | По умолчанию | Назначение |
+|---|---|---|
+| `alias` | — | Имя стенда для выбора сервером (`server:"prod"`). |
+| `base_url` | — | Адрес API `config_server` (http/https). Обязательно. |
+| `username` / `password` | — | Учётная запись с правом записи. |
+| `readonly_username` / `readonly_password` | — | Необязательная учётная запись только для чтения (read-инструменты используют её). |
+| `gitlab_token` | — | Токен для `download_release` (если не задан — используется значение сервера/окружения). |
+| `insecure_skip_verify` | `false` | Отключить проверку TLS-сертификата (самоподписанные стенды). |
+| `front_roots` | `[]` | Разрешённые каталоги локальных сборок фронта (jail). Пусто — `update_front` запрещён. |
+| `timeout_sec` | `30` | Таймаут обычных запросов. |
+| `upload_timeout_sec` | `300` | Таймаут загрузки фронта и синхронной выгрузки релиза. |
+| `task_poll_max_sec` | `120` | Максимум ожидания задачи при `wait=true`. |
+| `task_poll_interval_sec` | `2` | Интервал опроса задачи. |
+| `max_output_bytes` | `100000` | Лимит длины вывода задачи (обрезается, хвост сохраняется). |
+| `max_upload_bytes` | `536870912` | Лимит суммарного размера сборки фронта (512 МиБ). |
+| `max_concurrent_mutations` | `1` | Максимум одновременных изменяющих операций на сервер. |
+
+## Секреты
+
+Два способа, оба безопасны (не попадают в репозиторий):
+
+**1. Переменные окружения** — подстановка `${VAR}` в `config.json`:
+
+```json
+{ "password": "${OMNI_PASSWORD}" }
+```
+
+Переменная должна быть задана в окружении процесса MCP-сервера. Если её нет —
+сервер откажется стартовать и явно укажет имя переменной (fail-closed).
+
+**2. `config.local.json`** — файл рядом с `config.json` (в `.gitignore`),
+накладывается поверх: объекты сливаются, серверы — по `alias`.
+
+```json
+{
+  "servers": [
+    { "alias": "prod", "password": "реальный-пароль" }
+  ],
+  "read_only": false
+}
+```
+
+## Shorthand для одного сервера
+
+Вместо массива `servers` можно задать корневые поля — это один сервер с
+алиасом `default`:
+
+```json
+{
+  "base_url": "http://10.20.30.40:5005",
+  "username": "${OMNI_USER}",
+  "password": "${OMNI_PASSWORD}"
+}
+```
+
+## Несколько стендов
+
+Каждому стенду — свой `alias`; инструменты принимают аргумент `server`:
+
+```json
+{
+  "servers": [
+    { "alias": "prod",  "base_url": "http://10.20.30.40:5005", "username": "${P_USER}", "password": "${P_PASS}" },
+    { "alias": "stage", "base_url": "http://10.20.31.40:5005", "username": "${S_USER}", "password": "${S_PASS}" }
+  ],
+  "default": "prod",
+  "allow_hosts": ["10.20.30.40", "10.20.31.40"]
+}
+```
+
+Пример целиком — [../examples/config.multi-server.json](../examples/config.multi-server.json).
+
+## Режим «только чтение» (наблюдатель)
+
+Для мониторинга удобно поднять отдельный инстанс без права изменений:
+
+```json
+{
+  "servers": [{ "alias": "prod", "base_url": "http://10.20.30.40:5005",
+                "readonly_username": "${OMNI_RO_USER}",
+                "readonly_password": "${OMNI_RO_PASSWORD}" }],
+  "read_only": true
+}
+```
+
+Пример — [../examples/config.readonly-observer.json](../examples/config.readonly-observer.json).
+
+## Проверка конфига
+
+```bash
+./omnichannel-mcp --check-config -config config.json
+```
+
+Печатает итоговый (слитый) конфиг с замаскированными секретами, список серверов
+и `default`. Код возврата ≠ 0 при ошибке — удобно для CI.