127 lines
6.3 KiB
Markdown
127 lines
6.3 KiB
Markdown
# 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). Внутренний проект компании.
|