# omnichannel-configserver-mcp

MCP-сервер для управления платформой **Omnichannel** через API
[`config_server`](../API.md): развёртывание релизов и эксплуатация — из любого
AI-ассистента, без веб-интерфейса.

Сервер реализует [Model Context Protocol](https://modelcontextprotocol.io) и
работает как обычный stdio-процесс: Claude Desktop, Cursor или любой другой
MCP-клиент запускает его локально, а он транслирует запросы ассистента в HTTP API
`config_server`. Состояния не хранит.

## Возможности

- **Развёртывание** — схема и манифест стенда, выгрузка релиза (пакеты и
  образы), запуск сервисов на одном или нескольких серверах, обновление фронта.
- **Эксплуатация** — сводка по стенду, статусы сервисов и хостов, аудит задач
  агентов, журналы миграций, диагностика сопоставления IP.
- **Конфигурация** — чтение и изменение compose/env, версии и безопасный откат,
  повторная выдача конфига агенту.
- **Безопасность** — режим «только чтение», отдельные read-only креды,
  подтверждение разрушительных операций, секреты только из окружения.

## Требования

- Запущенный **`config_server` 1.1.0+**, доступный по сети (`http://host:5005`).
- Учётная запись `config_server`.
- **Go 1.27+** для сборки.
- MCP-клиент, поддерживающий stdio-серверы.

## Быстрый старт

```bash
export GOPRIVATE=git.totmin.ru
go build -o omnichannel-configserver-mcp .
./omnichannel-configserver-mcp --health            # -> ok

cp examples/config.single-server.json config.json   # укажите base_url
export OMNI_USER=admin OMNI_PASSWORD='...'
./omnichannel-configserver-mcp --check-config -config config.json
```

Подключение к клиенту (общий вид):

```json
{
  "mcpServers": {
    "omnichannel-configserver-mcp": {
      "command": "/opt/omnichannel-configserver-mcp/omnichannel-configserver-mcp",
      "args": ["-config", "/opt/omnichannel-configserver-mcp/config.json"],
      "env": { "OMNI_USER": "admin", "OMNI_PASSWORD": "СЕКРЕТ" }
    }
  }
}
```

Проверка: попросите ассистента «покажи, что сейчас на стенде» — он вызовет
`server_info` и `overview`.

## Пример: деплой за несколько шагов

**Один сервис** (уже зарегистрирован в `config_server`):

> «Обнови compose сервиса `demo_web` на образ `nginx:1.27`, подними и дождись
> результата.»

Ассистент: `set_compose` → `deploy` → `get_task` → `overview`.

**Релиз на несколько серверов:**

> «Сохрани schema.json и manifest.json, разложи хосты, скачай релиз с образами,
> дождись завершения и запусти сервисы.»

Ассистент: `save_deployment_files` → `ip_match` → `seed_hosts` →
`download_release` → `release_job` → `start_services` → `deployment_tasks` →
`overview`.

Подробные playbooks (1 сервер, N серверов, фронт, откат) с форматами
`schema.json`/`manifest.json` — [docs/deployment.md](docs/deployment.md).
Готовые формулировки промптов — [examples/prompts.md](examples/prompts.md).

## Демо без прода

```bash
docker compose -f examples/demo/docker-compose.yml up -d   # локальный config_server v1.1.0
go build -o omnichannel-configserver-mcp .
python3 examples/demo/demo.py                              # сквозной сценарий через MCP
python3 examples/demo/e2e.py                               # + реальный config-agent: deploy/restart/down
docker compose -f examples/demo/docker-compose.yml down -v
```

Подробнее — [examples/demo/README.md](examples/demo/README.md).

## Документация

- [docs/getting-started.md](docs/getting-started.md) — установка и первое подключение
- [docs/configuration.md](docs/configuration.md) — полный справочник конфигурации
- [docs/tools.md](docs/tools.md) — все 36 инструментов
- [docs/deployment.md](docs/deployment.md) — развёртывание: 1 сервер, N серверов, фронт, откат
- [docs/operations.md](docs/operations.md) — эксплуатация и диагностика
- [docs/security.md](docs/security.md) — модель безопасности
- [docs/architecture.md](docs/architecture.md) — как устроено внутри
- [docs/api-compatibility.md](docs/api-compatibility.md) — версии API
- [docs/mcp-clients.md](docs/mcp-clients.md) — подключение к клиентам

## Безопасность (кратко)

- `read_only: true` по умолчанию; мутации требуют явного `read_only=false`.
- Разрушительные операции требуют `confirm="true"`.
- Read-инструменты могут ходить под отдельными read-only кредами.
- Секреты — только из переменных окружения или `config.local.json` (не в git).
- Подробно — [docs/security.md](docs/security.md).

## Разработка

```bash
export GOPRIVATE=git.totmin.ru
make build      # собрать бинарник
make ci         # build + test(race) + lint + tidy-check
make demo       # поднять локальный стенд и прогнать сквозной сценарий
```

Подробнее — [CONTRIBUTING.md](CONTRIBUTING.md).

## Лицензия

Apache-2.0 — см. [LICENSE](LICENSE). Внутренний проект компании.