Help:13-alpha MCP

Архитектура

MCP — открытый стандарт, через который LLM-клиенты (Claude Desktop, Cursor, VS Code, OpenWebUI и др.) вызывают внешние инструменты. Svacer MCP соединяет одно с другим: 8 инструментов поверх публичного REST API Svacer, которые LLM выбирает и вызывает в ответ на обычный текстовый запрос. Вместо ручной последовательности «открыть UI, найти проект, выбрать снимок, применить фильтр» достаточно сформулировать вопрос в чате — например, «сколько критических предупреждений в последнем снимке bash?» — и получить ответ. Необходимые вызовы инструментов модель выполняет самостоятельно.

Архитектура MCP-сервер

Поток запроса: LLM-клиент отправляет MCP-вызов через STDIO или Streamable HTTP → server.py передаёт его в выбранный инструмент из tools/ → инструмент проверяет параметры и обращается к api_client.py → клиент получает JWT от auth.py (модуль автоматически обновляет токен по истечении срока действия или при ответе 401) → запрос отправляется в Svacer REST API.

Установка

Установка Svacer MCP, подключение клиентов и конфигурация.

Требования

• Python 3.10+
• Доступ к Svacer-серверу: URL + логин/пароль

Режим STDIO

Подходит для настольных клиентов: Claude Desktop, Claude Code, Cursor, VS Code.

git clone https://gitlab.ispras.ru/svacerai/mcp.git && cd mcp

python3 -m venv .venv
.venv/bin/pip install -e .

cp .env.example .env
# Отредактировать .env — указать URL и учётные данные Svacer

# Проверить запуск (сервер ожидает данные на stdin; для выхода — Ctrl+C)
.venv/bin/svacer-mcp

После pip install -e . в окружении становится доступна команда svacer-mcp — её указывают в конфигурации клиентов ниже.

Режим HTTP (Docker)

Подходит для веб-клиентов (OpenWebUI) и удалённого доступа.

Требования: Docker, Docker Compose.

cp .env.example .env

# В .env обязательно задать SVACER_MCP_TOKEN — без него сервер не запускается
echo "SVACER_MCP_TOKEN=$(openssl rand -hex 32)" >> .env

docker compose up -d

# MCP endpoint: http://localhost:8002/mcp
# Клиенты передают заголовок: Authorization: Bearer <SVACER_MCP_TOKEN>

Внешний порт хоста задаётся переменной MCP_PORT (по умолчанию 8002), внутри контейнера сервер всегда слушает порт 8000.

Подключение клиентов

Claude Desktop

Файл конфигурации: ~/.config/Claude/claude_desktop_config.json (Linux) или %APPDATA%\Claude\claude_desktop_config.json (Windows).

Укажите абсолютный путь к svacer-mcp из вашего venv (which svacer-mcp в активированном venv или /path/to/mcp/.venv/bin/svacer-mcp).

{
  "mcpServers": {
    "svacer": {
      "command": "/path/to/mcp/.venv/bin/svacer-mcp",
      "env": {
        "SVACER_URL": "https://your-svacer.example.com",
        "SVACER_LOGIN": "your-login",
        "SVACER_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code

claude mcp add svacer \
  -e SVACER_URL=https://your-svacer.example.com \
  -e SVACER_LOGIN=your-login \
  -e SVACER_PASSWORD=your-password \
  -- /path/to/mcp/.venv/bin/svacer-mcp

VS Code

Файл .vscode/mcp.json в корне рабочей директории:

{
  "servers": {
    "svacer": {
      "type": "stdio",
      "command": "/path/to/mcp/.venv/bin/svacer-mcp",
      "env": {
        "SVACER_URL": "https://your-svacer.example.com",
        "SVACER_LOGIN": "your-login",
        "SVACER_PASSWORD": "your-password"
      }
    }
  }
}

Cursor

Файл .cursor/mcp.json в корне проекта или глобально:

{
  "mcpServers": {
    "svacer": {
      "command": "/path/to/mcp/.venv/bin/svacer-mcp",
      "env": {
        "SVACER_URL": "https://your-svacer.example.com",
        "SVACER_LOGIN": "your-login",
        "SVACER_PASSWORD": "your-password"
      }
    }
  }
}

OpenWebUI

1. Развернуть через Docker (см. «Режим HTTP» выше).
2. Открыть Settings → Tools (или Admin Panel → Settings → Tools).
3. Добавить сервер:
   • http://localhost:8002/mcp — если OpenWebUI работает на хосте, снаружи Docker.
   • http://svacer-mcp:8000/mcp — если OpenWebUI развёрнут в той же compose-сети, что и svacer-mcp (имя берётся из docker-compose.yml → service name, порт 8000 — внутренний порт контейнера).
4. Тип подключения: MCP (Streamable HTTP).
5. В настройках инструмента указать заголовок Authorization: Bearer <SVACER_MCP_TOKEN> (значение — то же, что в .env сервера).
6. Сохранить — инструменты появятся в чате.

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

Переменная	По умолчанию	Описание
SVACER_URL	https://svacer-demo.ispras.ru	URL Svacer-сервера
SVACER_LOGIN	admin	Логин
SVACER_PASSWORD	admin	Пароль
SVACER_TIMEOUT	30	Тайм-аут HTTP-запросов к Svacer, секунды
SVACER_TRANSPORT	stdio	Режим транспорта: stdio или http
SVACER_HTTP_PORT	8000	TCP-порт сервера в режиме HTTP (внутри контейнера)
SVACER_MCP_TOKEN	(не задано)	Bearer-токен для клиентов /mcp. Обязателен при SVACER_TRANSPORT=http, в режиме STDIO игнорируется. Генерация: openssl rand -hex 32
SVACER_MCP_RESOURCE_URL	http://localhost:<HTTP_PORT>	Публичный URL MCP-сервера для заголовка WWW-Authenticate (RFC 9728). Задаётся при работе за обратным прокси
SVACER_TOOLS	(не задано)	Список инструментов через запятую. Если не задано, регистрируются все 8
MCP_PORT	8002	Внешний порт хоста при запуске через docker compose (отображается на внутренний SVACER_HTTP_PORT)

Переменные читаются из .env или из окружения. Для STDIO-клиентов их можно указать в секции env конфигурации клиента.

Ограничение набора инструментов

Чтобы запустить сервер с подмножеством инструментов (например, для уменьшения объёма контекста у модели или разграничения доступа), задайте SVACER_TOOLS:

SVACER_TOOLS=get_projects,get_snapshots,get_markers

Допустимые имена: get_projects, get_snapshots, get_warnings, get_markers, get_project_stats, get_project_groups, get_advanced_file_preview, get_diff. Неизвестное имя в списке приводит к ошибке при запуске. Если переменная пустая или не задана, регистрируются все 8 инструментов.

Несколько экземпляров сервера

Параллельный запуск нескольких MCP-серверов поддерживается без ограничений.

• В режиме STDIO каждая запись в конфигурации клиента описывает отдельный процесс — несколько подключений к разным экземплярам Svacer задаются простым перечислением.
• В режиме HTTP запускаются независимые контейнеры на разных хост-портах: например, MCP_PORT=8002 для одного экземпляра и MCP_PORT=8003 для другого. Для каждого контейнера задаётся собственный SVACER_MCP_TOKEN.

Безопасность

• STDIO: сервер не открывает сетевых портов и обменивается данными через стандартные потоки ввода/вывода процесса.
• Streamable HTTP: эндпоинт /mcp требует заголовок Authorization: Bearer <SVACER_MCP_TOKEN>. Запросы без токена или с неверным значением получают ответ 401 и заголовок WWW-Authenticate: Bearer .... Токен является разделяемым секретом и не заменяет TLS, а дополняет его: при работе за обратным прокси необходимо использовать HTTPS, а сам токен передавать только по защищённому каналу.
• Без SVACER_MCP_TOKEN HTTP-сервер не запускается.
• Учётные данные admin/admin предназначены только для тестового стенда. В рабочем окружении необходимо задать собственные логин и пароль через переменные окружения.
• Файл .env не должен добавляться в систему контроля версий.

Передача токена клиентом

Большинство HTTP-клиентов MCP (OpenWebUI и др.) позволяют задать произвольный заголовок Authorization в настройках инструмента — указывается значение Bearer <токен>. Для ручной проверки:

curl -H "Authorization: Bearer $SVACER_MCP_TOKEN" \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json, text/event-stream' \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' \
     http://localhost:8002/mcp