# Конфигурация

Конфиг — JSON-файл (по умолчанию `config.json`), который задаёт подключения к
`config_server` и политику безопасности. Рядом можно положить
`config.local.json` с секретами — он накладывается поверх и не коммитится.

## Как задать путь к конфигу

Приоритет (первый найденный):

1. аргумент инструмента `config_path` (для обёрток; обычно не нужен);
2. флаг запуска `-config /path/config.json`;
3. каталог из переменной окружения `OMNI_CONFIG_DIR` (в нём берётся
   `omnichannel-configserver-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-configserver-mcp --check-config -config config.json
```

Печатает итоговый (слитый) конфиг с замаскированными секретами, список серверов
и `default`. Код возврата ≠ 0 при ошибке — удобно для CI.