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,109 @@
+# Быстрый старт
+
+`omnichannel-mcp` — это **MCP-сервер**: программа, которую AI-ассистент
+(Claude Desktop, Cursor, Continue и любой другой MCP-клиент) запускает как
+локальный процесс и через которую получает доступ к платформе Omnichannel.
+Сервер не хранит состояние и не имеет UI: он лишь транслирует запросы агента в
+HTTP API `config_server`.
+
+## Что понадобится
+
+1. **Запущенный `config_server`** (версия 1.1.0 или новее), доступный по сети.
+   По умолчанию — `http://<host>:5005`. Проверить: `curl http://<host>:5005/health` → `OK`.
+2. **Учётная запись** `config_server` (логин/пароль администратора).
+3. **MCP-клиент**, поддерживающий stdio-серверы (Claude Desktop, Cursor и др.).
+4. Для сборки — **Go 1.27+** и доступ к общему тулкиту (Go-модуль
+   `forge-toolkit` на `git.totmin.ru`; задайте `GOPRIVATE=git.totmin.ru`).
+
+## 1. Сборка
+
+```bash
+cd omnichannel-mcp
+export GOPRIVATE=git.totmin.ru
+go build -o omnichannel-mcp .
+./omnichannel-mcp --health          # -> ok
+```
+
+## 2. Конфигурация
+
+Скопируйте пример и задайте адрес и креды:
+
+```bash
+cp examples/config.single-server.json config.json
+```
+
+```json
+{
+  "servers": [
+    {
+      "alias": "prod",
+      "base_url": "http://10.20.30.40:5005",
+      "username": "${OMNI_USER}",
+      "password": "${OMNI_PASSWORD}"
+    }
+  ],
+  "default": "prod",
+  "read_only": false
+}
+```
+
+Секреты удобно держать в переменных окружения или в `config.local.json`
+(подробно — [configuration.md](configuration.md)).
+
+Проверьте конфиг (секреты маскируются) — это самая частая причина проблем:
+
+```bash
+export OMNI_USER=admin OMNI_PASSWORD='...'
+./omnichannel-mcp --check-config -config config.json
+```
+
+## 3. Подключение к MCP-клиенту
+
+Общий вид конфигурации (для любого клиента, поддерживающего `mcpServers`):
+
+```json
+{
+  "mcpServers": {
+    "omnichannel-mcp": {
+      "command": "/opt/omnichannel-mcp/omnichannel-mcp",
+      "args": ["-config", "/opt/omnichannel-mcp/config.json"],
+      "env": {
+        "OMNI_USER": "admin",
+        "OMNI_PASSWORD": "СЕКРЕТ"
+      }
+    }
+  }
+}
+```
+
+Готовые сниппеты для конкретных клиентов — [mcp-clients.md](mcp-clients.md).
+
+## 4. Проверка
+
+Попросите ассистента:
+
+> «Проверь подключение к Omnichannel и покажи, что сейчас на стенде.»
+
+Ассистент вызовет `server_info` (версия API и режим), затем `overview` (сводка).
+Если видите корректную версию `1.1.0` и список сервисов — всё работает.
+
+## 5. Первый деплой
+
+Самый быстрый сценарий для уже зарегистрированного сервиса:
+
+> «Обнови compose сервиса `demo_web` на образ `nginx:1.27`, подними его и
+> дождись результата.»
+
+Последовательность вызовов и подробные сценарии (1 сервер, N серверов, фронт,
+откат) — [deployment.md](deployment.md). Готовые промпты —
+[../examples/prompts.md](../examples/prompts.md).
+
+## Демо-стенд (без прода)
+
+Поднять локальный `config_server` и прогнать сквозной пример:
+
+```bash
+docker compose -f examples/demo/docker-compose.yml up -d
+go build -o omnichannel-mcp .
+python3 examples/demo/demo.py
+```