Help:13-alpha MCP

From Svacer Wiki
Revision as of 10:52, 21 May 2026 by Mitrofanov (talk | contribs)

Архитектура

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

architectureMCP
Архитектура 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

Инструменты

Примеры сценариев

Retrieved from "https://svacer.ispras.ru/mediawiki/index.php?title=Help:13-alpha_MCP&oldid=3490"