Svacer Wiki - User contributions [en]

Help:13-alpha MCP

2026-05-26T21:12:08Z

Vaclovas: /* Установка */

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

[[File:Архитектура MCP.png|thumb|none|x800px|alt=architectureMCP|Архитектура MCP-сервера]]

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

== Установка ==

Svacer MCP может быть подключён к любому серверу Svacer версии 12 и выше. В данном разделе описывается установка Svacer MCP, подключение клиентов и конфигурация.
git clone <nowiki>https://gitlab.ispras.ru/vaclovas/svacermcp.git</nowiki> && cd svacermcp
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .

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

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

=== Режим STDIO ===
Подходит для настольных клиентов: Claude Desktop, Claude Code, Cursor, VS Code.
cp .env.example .env
# Отредактировать .env — указать URL и учётные данные Svacer

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

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

=== Режим 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: <nowiki>http://localhost:8002/mcp</nowiki>
# Клиенты передают заголовок: Authorization: Bearer <SVACER_MCP_TOKEN>

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

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

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

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

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

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

==== VS Code ====
Файл <code>.vscode/mcp.json</code> в корне рабочей директории:

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

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

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

==== OpenWebUI ====
# Развернуть через Docker (см. [[Help:13-alpha MCP#Режим HTTP (Docker)|Режим HTTP]]).
# Открыть '''Settings → Tools''' (или '''Admin Panel → Settings → Tools''').
# Добавить сервер:
#* <code><nowiki>http://localhost:8002/mcp</nowiki></code> — если OpenWebUI работает на хосте, снаружи Docker.
#* <code><nowiki>http://svacer-mcp:8000/mcp</nowiki></code> — если OpenWebUI развёрнут в той же compose-сети, что и <code>svacer-mcp</code> (имя берётся из <code>docker-compose.yml</code> → service name, порт 8000 — внутренний порт контейнера).
# Тип подключения: '''MCP (Streamable HTTP)'''.
# В настройках инструмента указать заголовок <code>Authorization: Bearer <SVACER_MCP_TOKEN></code> (значение — то же, что в <code>.env</code> сервера).
# Сохранить — инструменты появятся в чате.

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

==== Ограничение набора инструментов ====
Чтобы запустить сервер с подмножеством инструментов (например, для уменьшения объёма контекста у модели или разграничения доступа), задайте <code>SVACER_TOOLS</code>:
SVACER_TOOLS=get_projects,get_snapshots,get_markers
Допустимые имена: <code>get_projects</code>, <code>get_snapshots</code>, <code>get_warnings</code>, <code>get_markers</code>, <code>get_project_stats</code>, <code>get_project_groups</code>, <code>get_advanced_file_preview</code>, <code>get_diff</code>. Неизвестное имя в списке приводит к ошибке при запуске. Если переменная пустая или не задана, регистрируются все 8 инструментов.

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

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

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

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

==== Передача токена клиентом ====
Большинство HTTP-клиентов MCP (OpenWebUI и др.) позволяют задать произвольный заголовок <code>Authorization</code> в настройках инструмента — указывается значение <code>Bearer <токен></code>. Для ручной проверки:
curl -H "Authorization: Bearer $SVACER_MCP_TOKEN" \
<nowiki> </nowiki> -H 'Content-Type: application/json' \
<nowiki> </nowiki> -H 'Accept: application/json, text/event-stream' \
<nowiki> </nowiki> -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' \
<nowiki> </nowiki> <nowiki>http://localhost:8002/mcp</nowiki>

== Инструменты ==
Справочник по 8 инструментам Svacer MCP. Типичный порядок вызовов: <code>get_projects</code> → <code>get_snapshots</code> → любой из аналитических инструментов.
{| class="wikitable"
!Инструмент
!Назначение
|-
|get_projects
|Список проектов с ветками — точка входа
|-
|get_snapshots
|Снимки конкретной ветки, от нового к старому
|-
|get_project_stats
|Агрегированные метрики снимка: severity / review / checker
|-
|get_markers
|Компактный список маркеров с серверной фильтрацией
|-
|get_warnings
|Полные предупреждения с трассами и историей разметки
|-
|get_diff
|Сравнение двух снимков: new / missing / modified / matched
|-
|get_advanced_file_preview
|Фрагмент исходного кода вокруг строки
|-
|get_project_groups
|Группа проектов по имени или UUID
|}

=== get_projects ===
Список всех проектов с ветками. Точка входа: с этого вызова начинается практически любой сценарий — он возвращает <code>project_id</code> и <code>branch_id</code>, необходимые для последующих запросов.

'''Параметров нет.'''

'''Вызов:'''
get_projects()

'''Ответ:'''
[
{
"project_id": "91630e84-db2f-4d8c-8716-68b7fdf17a66",
"project_name": "bash",
"created": "2021-12-13T13:22:42.122456Z",
"created_by": "admin",
"branches": [
{
"branch_id": "77f66b9e-0453-4ae9-a187-88950b4c4bc4",
"branch_name": "master",
"created": "2021-12-13T13:22:42.394812Z"
}
]
}
]
----

=== get_snapshots ===
Список снимков для конкретной ветки проекта, от нового к старому.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|project_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|branch_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|name_filter
|string
|нет
|Подстрока или regex для фильтра по имени снимка
|}

'''Вызов:'''
get_snapshots(
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4"
)

'''Ответ:'''
[
{
"snapshot_id": "b42cb563-86f4-4f96-900a-7782163327c9",
"name": "Snapshot 2020-03-25 09:09:41 +0300",
"import_time": "2020-03-25T09:09:41.837296Z",
"commit_hash": null,
"markers_count": 297,
"link": "<nowiki>https://svacer-demo.ispras.ru/</nowiki>..."
}
]
----

=== get_project_stats ===
Агрегированные метрики по снимку: общее количество предупреждений, распределение по критичности, по статусу разметки, по детекторам. Наиболее быстрый способ получить общую картину по проекту.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|project_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|branch_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|snapshot_id
|string (UUID)
|да
|Из <code>get_snapshots</code>
|}

'''Вызов:'''
get_project_stats(
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4",
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9"
)

'''Ответ:'''
{
"total_warnings": 771,
"by_severity": {
"Critical": 1,
"Major": 1,
"Unspecified": 769
},
"by_review_status": {
"Confirmed": 1,
"False Positive": 1,
"Undecided": 767,
"Unclear": 1,
"Won't fix": 1
},
"by_checker": {
"PROC_USE.VULNERABLE": 337,
"UNUSED_FUNC_RES.REWRITE.MINOR": 44,
"UNREACHABLE_CODE": 28,
"DEREF_AFTER_NULL.EX": 27,
"NULL_AFTER_DEREF": 27
}
}
----

=== get_markers ===
Компактный список маркеров с серверной фильтрацией. Основной инструмент для перечисления и обзора: его следует предпочитать <code>get_warnings</code>, когда не требуются развёрнутые поля — трассы и история разметки.

По умолчанию ответ ограничен 30 маркерами и содержит компактный набор полей. Подробнее об ограничении объёма см. раздел [[Help:13-alpha MCP#Про объём ответа|Про объём ответа]].

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|project_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|branch_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|snapshot_id
|string (UUID)
|да
|Из <code>get_snapshots</code>
|-
|severity
|string[]
|нет
|<code>Critical</code>, <code>Major</code>, <code>Minor</code>, <code>Unspecified</code>. Фильтр по <code>review.severity</code> применяется на стороне коннектора
|-
|review
|string[]
|нет
|<code>Confirmed</code>, <code>Won't fix</code>, <code>False Positive</code>, <code>Unclear</code>
|-
|warnClass
|string[]
|нет
|Идентификатор детектора (<code>DEREF_AFTER_NULL</code>, …)
|-
|file
|string[]
|нет
|Подстрока пути к файлу
|-
|traces
|bool
|нет
|Включить трассы маркеров
|-
|checker_info
|bool
|нет
|Включить метаданные детектора (CWE, описание)
|-
|review_history
|bool
|нет
|Включить историю изменений разметки
|-
|comment_history
|bool
|нет
|Включить комментарии к маркеру
|-
|custom_filter
|string
|нет
|Имя или идентификатор сохранённого фильтра из веб-интерфейса Svacer
|-
|limit
|int
|нет
|Максимальное количество маркеров в ответе (по умолчанию 30). Значение 0 снимает ограничение
|-
|fields
|string[]
|нет
|Список разрешённых полей маркера верхнего уровня. По умолчанию — компактный набор <code>id, warnClass, file, line, msg, function, review</code>. Значение <code>["*"]</code> возвращает все поля коннектора (<code>id, warnClass, file, line, msg, tool, function, mtid, review</code>, а также <code>traces</code>/<code>checkerInfo</code>/<code>review_history</code>/<code>comments</code>, если они запрошены). Допустим и произвольный список, например <code>["id","warnClass"]</code>
|}

'''Вызов:'''
get_markers(
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4",
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",
warnClass=["PROC_USE.VULNERABLE"]
)

'''Ответ:'''
{
"total_count": 341,
"returned_count": 30,
"truncated": true,
"filters_applied": {"warnClass": ["PROC_USE.VULNERABLE"]},
"markers": [
{
"id": "e05bb35b-a95e-4eb2-85ae-3101b788f07d",
"warnClass": "PROC_USE.VULNERABLE.TEMP",
"file": "/.build/lib/sh/tmpfile.c",
"line": 160,
"msg": "Use of vulnerable function 'mktemp' at tmpfile.c:160. ...",
"function": "sh_mktmpname",
"review": null
}
]
}

<code>total_count</code> отражает количество маркеров, удовлетворяющих фильтру до применения ограничения; <code>returned_count</code> — количество маркеров, фактически содержащихся в <code>markers</code>. При <code>truncated: true</code> следует либо сузить фильтры (<code>severity</code>, <code>warnClass</code>, <code>file</code>), либо передать <code>limit=0</code> для получения полного списка. Поля <code>tool</code> и <code>mtid</code> возвращаются только при <code>fields=["*"]</code>.
----

=== get_warnings ===
Полные предупреждения с детальной разметкой. Ответ значительно объёмнее, чем у <code>get_markers</code>, поэтому инструмент следует использовать только тогда, когда нужны поля, отсутствующие в компактной форме: <code>traces</code>, <code>review_history</code>, <code>checker_info</code>, <code>comment_history</code>.

Лимит по умолчанию — 30; при включённых <code>traces</code>, <code>review_history</code> или <code>comment_history</code> он автоматически снижается до 8, поскольку такие предупреждения существенно объёмнее.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|project_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|branch_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|snapshot_id
|string (UUID)
|да
|Из <code>get_snapshots</code>
|-
|severity
|string[]
|нет
|<code>Critical</code>, <code>Major</code>, <code>Minor</code>, <code>Unspecified</code>. Фильтр по <code>review.severity</code>, применяется на стороне коннектора
|-
|review
|string[]
|нет
|<code>Confirmed</code>, <code>Won't fix</code>, <code>False Positive</code>, <code>Unclear</code>
|-
|warnClass
|string[]
|нет
|Идентификатор детектора
|-
|file
|string[]
|нет
|Подстрока пути к файлу
|-
|traces
|bool
|нет
|Включить трассы. Активирует режим расширенных полей (лимит по умолчанию — 8)
|-
|checker_info
|bool
|нет
|Включить метаданные детектора (CWE, описание)
|-
|review_history
|bool
|нет
|Включить историю разметки. Режим расширенных полей
|-
|comment_history
|bool
|нет
|Включить комментарии. Режим расширенных полей
|-
|custom_filter
|string
|нет
|Имя или идентификатор сохранённого фильтра
|-
|limit
|int
|нет
|Максимальное количество предупреждений в ответе. По умолчанию — 30, в режиме расширенных полей — 8. Значение 0 снимает ограничение. Явно заданное <code>limit</code> отменяет автоматическое снижение
|-
|fields
|string[]
|нет
|См. описание в <code>get_markers</code>
|}
'''Вызов:'''
get_warnings(
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4",
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",
severity=["Critical"],
review_history=True,
traces=True
)

'''Ответ:'''
{
"total_count": 1,
"returned_count": 1,
"truncated": false,
"filters_applied": {"severity": ["Critical"], "traces": true, "review_history": true},
"warnings": [
{
"id": "a3f21c90-1d4e-4b82-9f63-7c8e5d2a1b09",
"warnClass": "DEREF_AFTER_NULL.LOOP",
"file": "/.build/execute_cmd.c",
"line": 3327,
"msg": "Possible null pointer dereference of 'l' after loop exit.",
"function": "select_query",
"review": {"status": "Confirmed", "severity": "Critical"},
"review_history": [{"status": "Confirmed", "changed_by": "admin", "changed_at": "2021-12-13T14:00:00Z"}],
"traces": [{"file": "/.build/execute_cmd.c", "line": 3320, "msg": "Loop starts here; 'l' may exhaust the list."}]
}
]
}
----

=== get_diff ===
Сравнение двух снимков. Категории располагаются под ключом <code>markers</code>: <code>new_markers</code> (появилось в новом снимке), <code>missing_markers</code> (исчезло из нового), <code>modified_markers</code> (тот же идентификатор, изменился контекст), <code>matched_markers</code> (совпало в обоих). Параметры <code>project_id</code> и <code>branch_id</code> не требуются — достаточно UUID снимков.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|base_snapshot_id
|string (UUID)
|да
|Старый снимок
|-
|head_snapshot_id
|string (UUID)
|нет
|Новый снимок; если не указан, сравнение выполняется с предыдущим по времени
|-
|level
|int
|нет
|0 — только статистика; 1 — статистика и идентификаторы маркеров; 2 — полные маркеры по категориям
|-
|checker_info
|bool
|нет
|Метаданные детекторов для маркеров (только при <code>level >= 2</code>)
|-
|limit
|int
|нет
|Максимальное количество маркеров '''на каждую категорию''' при <code>level >= 2</code>. По умолчанию — 20, значение 0 снимает ограничение. Параметр игнорируется при <code>level < 2</code>
|-
|fields
|string[]
|нет
|См. описание в <code>get_markers</code>. Применяется к маркерам внутри категорий при <code>level >= 2</code>
|}

'''Вызов (<code>level=0</code>):'''
get_diff(
base_snapshot_id="72b3df7b-c15a-4e3d-8f92-a041dc6e5b87",
head_snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",
level=0
)

'''Ответ (<code>level=0</code>):'''
{
"stats": {
"context1": {"projectName": "paho.mqtt.c", "snapshotName": "Snapshot 2020-03-20 ..."},
"context2": {"projectName": "paho.mqtt.c", "snapshotName": "Snapshot 2020-03-25 ..."},
"scope": ["NEW", "MISSING", "MATCHED", "MODIFIED"],
"new": 9,
"missing": 12,
"modified": 98,
"matched": 187
}
}

'''Ответ (<code>level=2</code>)''' — каждая категория внутри <code>markers</code> оформляется и ограничивается независимо:
{
"stats": {"new": 50, "missing": 5, "modified": 0, "matched": 187},
"markers": {
"new_markers": {
"total_count": 50,
"returned_count": 20,
"truncated": true,
"markers": [
{"id": "a3f21c90-...", "warnClass": "DEREF_AFTER_NULL.LOOP", "file": "...", "line": 3327, "msg": "...", "function": "select_query", "review": null}
]
},
"missing_markers": {"total_count": 5, "returned_count": 5, "truncated": false, "markers": [...]},
"modified_markers": {"total_count": 0, "returned_count": 0, "truncated": false, "markers": []},
"matched_markers": {"total_count": 187, "returned_count": 20, "truncated": true, "markers": [...]}
}
}

Если требуется полное содержимое категории, следует увеличить <code>limit</code>, либо запросить нужные идентификаторы отдельным вызовом <code>get_markers</code>. Маркеры внутри категорий проходят ту же компактную обработку, что и в <code>get_warnings</code>: значение <code>fields=["*"]</code> возвращает фиксированный набор полей коннектора, а не произвольные «сырые» поля API.
----

=== get_advanced_file_preview ===
Фрагмент исходного кода из снимка вокруг указанной строки. Параметры <code>project_id</code> и <code>branch_id</code> не требуются — достаточно идентификатора снимка и пути к файлу.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|snapshot_id
|string (UUID)
|да
|UUID снимка
|-
|file_path
|string
|да
|Путь к файлу в том виде, в котором его возвращают <code>get_markers</code> и <code>get_warnings</code>
|-
|line
|int
|нет
|Центральная строка, нумерация с 1 (по умолчанию 1)
|-
|before
|int
|нет
|Количество строк до центральной (по умолчанию 0)
|-
|after
|int
|нет
|Количество строк после центральной (по умолчанию 99999 — до конца файла)
|}

'''Вызов:'''
get_advanced_file_preview(
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",
file_path="/.build/execute_cmd.c",
line=3327,
before=10,
after=10
)

'''Ответ:'''
{
"line": 3327,
"content": " for (l = list; l && --reply; l = l->next)\n\t;\n return (l->word->word);\n",
"total_lines": 6082
}
----

=== get_project_groups ===
Получить группу проектов по имени или UUID. Группы объединяют проекты в логические блоки — например, по команде или продукту.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|name_or_id
|string
|да
|Имя группы или её UUID
|}

'''Вызов:'''
get_project_groups(name_or_id="Linux Tools")

'''Ответ:'''
{
"project_group_id": "c4f8a2d1-3b7e-4f90-82ac-1d5e8f2b6c04",
"project_group_name": "Linux Tools",
"projects": [
{"id": "91630e84-db2f-4d8c-8716-68b7fdf17a66", "name": "bash"},
{"id": "d3a17f52-...", "name": "coreutils"}
]
}

<code>projects[].id</code> — это <code>project_id</code>, который далее передаётся в <code>get_snapshots</code>. Группы и проекты — разные сущности; идентификатор группы и идентификатор проекта не взаимозаменяемы.

== Примеры сценариев ==
Приведённые ниже запросы выполнены на демонстрационном стенде <code>svacer-demo.ispras.ru</code> с использованием OpenWebUI и модели <code>qwen3-coder:30b</code>. В любом другом MCP-клиенте с моделью достаточной мощности порядок вызовов будет аналогичным.

=== Про объём ответа ===
<code>get_markers</code>, <code>get_warnings</code> и <code>get_diff(level=2)</code> по умолчанию ограничивают объём ответа, чтобы не перегружать контекст модели:

* <code>get_markers</code> и <code>get_warnings</code> — 30 маркеров по умолчанию. Если у <code>get_warnings</code> включены <code>traces</code>, <code>review_history</code> или <code>comment_history</code>, лимит снижается до 8, поскольку такие маркеры значительно объёмнее.
* <code>get_diff(level=2)</code> — 20 маркеров на каждую категорию внутри <code>markers</code> (<code>new_markers</code>/<code>missing_markers</code>/<code>modified_markers</code>/<code>matched_markers</code>).

В ответе присутствуют поля <code>total_count</code>, <code>returned_count</code>, <code>truncated</code>. При <code>truncated: true</code> есть два варианта действий: сузить фильтр (<code>severity</code>, <code>warnClass</code>, <code>file</code>) либо явно увеличить <code>limit</code> (значение <code>limit=0</code> полностью снимает ограничение).

Поле <code>fields</code> определяет, какие ключи маркера возвращаются. По умолчанию применяется компактный набор <code>id, warnClass, file, line, msg, function, review</code> (а также <code>traces</code>/<code>checkerInfo</code>/<code>review_history</code>/<code>comments</code>, если они запрошены логическими флагами и пришли с сервера). Для полного маркера со всеми служебными ключами — <code>fields=["*"]</code>. Для произвольной выборки — список полей верхнего уровня, например <code>fields=["id","warnClass"]</code>. Поле <code>review</code> — объект <code>{status, severity, action}</code>; вложенные ключи в <code>fields</code> не поддерживаются, поэтому объект <code>review</code> запрашивается целиком.

=== Перечислить все проекты ===
<blockquote>Какие проекты есть в Svacer?</blockquote>

'''Цепочка вызовов:'''
# <code>get_projects()</code>

'''Ответ модели:'''
<blockquote>В Svacer доступно 6 проектов: bash, openssl, paho.mqtt.c, coturn, zstd, darpa. У каждого — одна ветка <code>master</code>.</blockquote>

=== Посмотреть снимки проекта ===
<blockquote>Какие снимки есть у paho.mqtt.c? Самый свежий когда?</blockquote>'''Цепочка вызовов:'''

# <code>get_projects()</code> — найти <code>project_id</code> и <code>branch_id</code>
# <code>get_snapshots(project_id=..., branch_id=...)</code>

'''Ответ модели:'''
<blockquote>У paho.mqtt.c 3 снимка. Самый свежий — «Snapshot 2020-03-25 09:09:41 +0300» (297 маркеров). Предыдущий — 20 марта (306 маркеров).</blockquote>Поле <code>commit_hash</code> может принимать значение <code>null</code>, если проект не сохраняет хэш коммита в <code>custom_properties</code>. Имена снимков произвольны: одни проекты записывают в имя дату, другие — коммит, третьи — свободный текст.

=== Сводка по проекту ===
<blockquote>Что в bash в последнем снимке? Сколько всего предупреждений, есть ли критические, какие топ-детекторы?</blockquote>

'''Цепочка вызовов:'''
# <code>get_projects()</code>
# <code>get_snapshots(project_id, branch_id)</code> — взять последний снимок
# <code>get_project_stats(project_id, branch_id, snapshot_id)</code>

'''Ответ модели:'''
<blockquote>В последнем снимке bash содержится 771 предупреждение:

* Критических: 1 (Confirmed)
* Major: 1 (Won't fix)
* Остальные: 769 (Unspecified — не размечались)

Топ-детекторы по количеству:

# <code>PROC_USE.VULNERABLE</code> — 337
# <code>UNUSED_FUNC_RES.REWRITE.MINOR</code> — 44
# <code>UNREACHABLE_CODE</code> — 28
# <code>DEREF_AFTER_NULL.EX</code> — 27
# <code>NULL_AFTER_DEREF</code> — 27
</blockquote>

<code>Unspecified</code> в <code>by_severity</code> — маркеры без ручной разметки, а не «низкий приоритет». Поле <code>by_checker</code> не сортируется, на большом снимке оно может содержать более 100 ключей — чтобы получить именно топ-N, следует явно сформулировать запрос: «топ-5 детекторов».

=== Тренд по нескольким снимкам ===
<blockquote>Как у openssl менялось число предупреждений за последние пять снимков? Покажи таблицей.</blockquote>

'''Цепочка вызовов:'''

# <code>get_projects()</code>
# <code>get_snapshots()</code> — взять список
# <code>get_project_stats()</code> × 5 — по каждому из последних пяти снимков

'''Ответ модели:'''
<blockquote>
{| class="wikitable"
|+
!Снимок
!Дата
!Всего
|-
|2020-04-30 05:49
|30.04.2020
|1252
|-
|2020-04-30 05:29
|30.04.2020
|1252
|-
|2020-04-30 05:08
|30.04.2020
|1252
|-
|2020-04-30 04:48
|30.04.2020
|1252
|-
|2020-04-30 04:22
|30.04.2020
|1252
|}
</blockquote>

На демонстрационном стенде указанные пять снимков openssl импортированы с интервалом в 20 минут одного дня и полностью идентичны — поэтому динамика отсутствует. На реальном проекте с историей релизов значения будут изменяться.

=== Найти срабатывания конкретного детектора ===
<blockquote>Где в bash срабатывает PROC_USE.VULNERABLE? Покажи список — файл, строка, что именно ругается. Достаточно первых десяти.</blockquote>

'''Цепочка вызовов:'''
# <code>get_projects()</code>
# <code>get_snapshots()</code>
# <code>get_markers(warnClass=["PROC_USE.VULNERABLE"])</code>

'''Ответ модели:'''
<blockquote>
# <code>/.build/lib/sh/tmpfile.c:160</code> — <code>mktemp()</code>, race condition. Рекомендуется <code>mkstemp()</code>.
# <code>/.build/lib/readline/shell.c:151</code> — <code>getenv()</code>, значение может быть подменено.
# <code>/.build/shell.c:415</code> — <code>getenv()</code> в <code>main()</code>.
# <code>/.build/lib/readline/complete.c:1516</code> — <code>getenv()</code>.
# <code>/.build/lib/sh/eaccess.c:115</code> — <code>strcat()</code>, рекомендуется <code>strncat()</code>.
</blockquote>

Фильтр <code>warnClass=["PROC_USE.VULNERABLE"]</code> охватывает все подклассы: <code>PROC_USE.VULNERABLE.TEMP</code>, <code>.GETENV</code>, <code>.STRCAT</code> и т. д. — всего 341 маркер. Несколько значений в одном параметре трактуются как логическое «ИЛИ»: <code>severity=["Critical","Major"]</code> возвращает маркеры обеих категорий.

В ответе будет <code>total_count: 341, returned_count: 30, truncated: true</code> — это ожидаемое поведение. Модель видит общий объём по <code>total_count</code> и при необходимости сужает запрос или вызывает <code>get_markers(..., limit=0)</code>, чтобы получить полный список.

=== Сравнить два снимка ===
<blockquote>Возьми два последних снимка paho.mqtt.c — что между ними изменилось? Сколько новых предупреждений, сколько починили?</blockquote>

'''Цепочка вызовов:'''
# <code>get_projects()</code>
# <code>get_snapshots()</code> — два последних
# <code>get_diff(base_snapshot_id="72b3df7b-...", head_snapshot_id="b42cb563-...", level=0)</code>

'''Ответ модели:'''
<blockquote>Между двумя последними снимками paho.mqtt.c:

* Новых: 12
* Удалённых: 13
* Изменённых: 99
* Совпадающих: 185

Удалено несколько больше, чем добавлено — общая картина практически не изменилась.</blockquote>

Категория <code>modified</code> — маркер, присутствующий в обоих снимках, у которого изменилось окружение (номер строки, контекст функции). Это не новая ошибка. На больших проектах рекомендуется начинать с <code>level=0</code> для получения статистики, при необходимости использовать <code>level=1</code> (только идентификаторы маркеров) и затем точечно вызывать <code>get_markers</code> с нужными фильтрами.

<code>level=2</code> возвращает полные маркеры по категориям, причём каждая категория по умолчанию ограничена 20 маркерами. Категории располагаются внутри <code>markers</code>: <code>new_markers</code>, <code>missing_markers</code>, <code>modified_markers</code>, <code>matched_markers</code>. Структура ответа в JSON: <code><nowiki>{"markers": {"new_markers": {"total_count": N, "returned_count": ..., "truncated": ..., "markers": [...]}, ...}}</nowiki></code>. Если требуется полное содержимое категории, следует увеличить <code>limit</code> или выполнить отдельный вызов <code>get_markers</code> по нужным идентификаторам.

=== Разобрать конкретное предупреждение ===
<blockquote>В bash есть один подтверждённый критикал — что-то про разыменование указателя. Покажи код вокруг этого места и объясни в чём проблема.</blockquote>

'''Цепочка вызовов:'''
# <code>get_projects()</code> → <code>get_snapshots()</code> — найти снимок bash
# <code>get_markers(severity=["Critical"], review=["Confirmed"])</code>
# <code>get_advanced_file_preview(file_path="/.build/execute_cmd.c", line=3327, before=10, after=10)</code>

'''Ответ модели:'''
<blockquote>Маркер <code>DEREF_AFTER_NULL.LOOP</code> в функции <code>select_query()</code>, строка 3327:
<code>for (l = list; l && --reply; l = l->next)

;

return (l->word->word); /* l может быть NULL после выхода из цикла */</code>

Если список заканчивается раньше, чем <code>reply</code> обнуляется, <code>l</code> станет <code>NULL</code> на последнем <code>l->next</code>, и следующий <code>l->word->word</code> — разыменование нулевого указателя.</blockquote><code>file_path</code> должен точно совпадать со значением, возвращённым маркером, включая ведущий префикс <code>/.build/...</code>. Это путь внутри сборочной директории Svacer, а не путь в исходном репозитории; соответствие в репозитории определяется по имени файла.

Для одиночной разметки удобно сразу запрашивать полный маркер с трассами: <code>get_markers(..., severity=["Critical"], review=["Confirmed"], traces=True, checker_info=True)</code>. Флаги <code>traces</code> и <code>checker_info</code> указывают серверу включить соответствующие поля в ответ; в выдаче они сохраняются и при значении <code>fields</code> по умолчанию. Значение <code>fields=["*"]</code> требуется лишь в том случае, когда дополнительно нужны <code>tool</code> и <code>mtid</code> — служебные ключи, исключённые из компактного набора.

Help:13-alpha MCP

2026-05-26T10:38:06Z

Vaclovas: /* Установка */

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

[[File:Архитектура MCP.png|thumb|none|x800px|alt=architectureMCP|Архитектура MCP-сервера]]

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

== Установка ==

Svacer MCP может быть подключён к любому серверу Svacer версии 12 и выше. В данном разделе описывается установка Svacer MCP, подключение клиентов и конфигурация.

<code>git clone <nowiki>https://gitlab.ispras.ru/vaclovas/svacermcp.git</nowiki> && cd svacermcp</code>

<code>python3 -m venv .venv</code>

<code>pip install -e .</code>

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

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

=== Режим STDIO ===
Подходит для настольных клиентов: Claude Desktop, Claude Code, Cursor, VS Code.
cp .env.example .env
# Отредактировать .env — указать URL и учётные данные Svacer

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

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

=== Режим 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: <nowiki>http://localhost:8002/mcp</nowiki>
# Клиенты передают заголовок: Authorization: Bearer <SVACER_MCP_TOKEN>

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

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

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

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

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

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

==== VS Code ====
Файл <code>.vscode/mcp.json</code> в корне рабочей директории:

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

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

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

==== OpenWebUI ====
# Развернуть через Docker (см. [[Help:13-alpha MCP#Режим HTTP (Docker)|Режим HTTP]]).
# Открыть '''Settings → Tools''' (или '''Admin Panel → Settings → Tools''').
# Добавить сервер:
#* <code><nowiki>http://localhost:8002/mcp</nowiki></code> — если OpenWebUI работает на хосте, снаружи Docker.
#* <code><nowiki>http://svacer-mcp:8000/mcp</nowiki></code> — если OpenWebUI развёрнут в той же compose-сети, что и <code>svacer-mcp</code> (имя берётся из <code>docker-compose.yml</code> → service name, порт 8000 — внутренний порт контейнера).
# Тип подключения: '''MCP (Streamable HTTP)'''.
# В настройках инструмента указать заголовок <code>Authorization: Bearer <SVACER_MCP_TOKEN></code> (значение — то же, что в <code>.env</code> сервера).
# Сохранить — инструменты появятся в чате.

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

==== Ограничение набора инструментов ====
Чтобы запустить сервер с подмножеством инструментов (например, для уменьшения объёма контекста у модели или разграничения доступа), задайте <code>SVACER_TOOLS</code>:
SVACER_TOOLS=get_projects,get_snapshots,get_markers
Допустимые имена: <code>get_projects</code>, <code>get_snapshots</code>, <code>get_warnings</code>, <code>get_markers</code>, <code>get_project_stats</code>, <code>get_project_groups</code>, <code>get_advanced_file_preview</code>, <code>get_diff</code>. Неизвестное имя в списке приводит к ошибке при запуске. Если переменная пустая или не задана, регистрируются все 8 инструментов.

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

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

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

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

==== Передача токена клиентом ====
Большинство HTTP-клиентов MCP (OpenWebUI и др.) позволяют задать произвольный заголовок <code>Authorization</code> в настройках инструмента — указывается значение <code>Bearer <токен></code>. Для ручной проверки:
curl -H "Authorization: Bearer $SVACER_MCP_TOKEN" \
<nowiki> </nowiki> -H 'Content-Type: application/json' \
<nowiki> </nowiki> -H 'Accept: application/json, text/event-stream' \
<nowiki> </nowiki> -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' \
<nowiki> </nowiki> <nowiki>http://localhost:8002/mcp</nowiki>

== Инструменты ==
Справочник по 8 инструментам Svacer MCP. Типичный порядок вызовов: <code>get_projects</code> → <code>get_snapshots</code> → любой из аналитических инструментов.
{| class="wikitable"
!Инструмент
!Назначение
|-
|get_projects
|Список проектов с ветками — точка входа
|-
|get_snapshots
|Снимки конкретной ветки, от нового к старому
|-
|get_project_stats
|Агрегированные метрики снимка: severity / review / checker
|-
|get_markers
|Компактный список маркеров с серверной фильтрацией
|-
|get_warnings
|Полные предупреждения с трассами и историей разметки
|-
|get_diff
|Сравнение двух снимков: new / missing / modified / matched
|-
|get_advanced_file_preview
|Фрагмент исходного кода вокруг строки
|-
|get_project_groups
|Группа проектов по имени или UUID
|}

=== get_projects ===
Список всех проектов с ветками. Точка входа: с этого вызова начинается практически любой сценарий — он возвращает <code>project_id</code> и <code>branch_id</code>, необходимые для последующих запросов.

'''Параметров нет.'''

'''Вызов:'''
get_projects()

'''Ответ:'''
[
{
"project_id": "91630e84-db2f-4d8c-8716-68b7fdf17a66",
"project_name": "bash",
"created": "2021-12-13T13:22:42.122456Z",
"created_by": "admin",
"branches": [
{
"branch_id": "77f66b9e-0453-4ae9-a187-88950b4c4bc4",
"branch_name": "master",
"created": "2021-12-13T13:22:42.394812Z"
}
]
}
]
----

=== get_snapshots ===
Список снимков для конкретной ветки проекта, от нового к старому.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|project_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|branch_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|name_filter
|string
|нет
|Подстрока или regex для фильтра по имени снимка
|}

'''Вызов:'''
get_snapshots(
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4"
)

'''Ответ:'''
[
{
"snapshot_id": "b42cb563-86f4-4f96-900a-7782163327c9",
"name": "Snapshot 2020-03-25 09:09:41 +0300",
"import_time": "2020-03-25T09:09:41.837296Z",
"commit_hash": null,
"markers_count": 297,
"link": "<nowiki>https://svacer-demo.ispras.ru/</nowiki>..."
}
]
----

=== get_project_stats ===
Агрегированные метрики по снимку: общее количество предупреждений, распределение по критичности, по статусу разметки, по детекторам. Наиболее быстрый способ получить общую картину по проекту.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|project_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|branch_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|snapshot_id
|string (UUID)
|да
|Из <code>get_snapshots</code>
|}

'''Вызов:'''
get_project_stats(
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4",
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9"
)

'''Ответ:'''
{
"total_warnings": 771,
"by_severity": {
"Critical": 1,
"Major": 1,
"Unspecified": 769
},
"by_review_status": {
"Confirmed": 1,
"False Positive": 1,
"Undecided": 767,
"Unclear": 1,
"Won't fix": 1
},
"by_checker": {
"PROC_USE.VULNERABLE": 337,
"UNUSED_FUNC_RES.REWRITE.MINOR": 44,
"UNREACHABLE_CODE": 28,
"DEREF_AFTER_NULL.EX": 27,
"NULL_AFTER_DEREF": 27
}
}
----

=== get_markers ===
Компактный список маркеров с серверной фильтрацией. Основной инструмент для перечисления и обзора: его следует предпочитать <code>get_warnings</code>, когда не требуются развёрнутые поля — трассы и история разметки.

По умолчанию ответ ограничен 30 маркерами и содержит компактный набор полей. Подробнее об ограничении объёма см. раздел [[Help:13-alpha MCP#Про объём ответа|Про объём ответа]].

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|project_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|branch_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|snapshot_id
|string (UUID)
|да
|Из <code>get_snapshots</code>
|-
|severity
|string[]
|нет
|<code>Critical</code>, <code>Major</code>, <code>Minor</code>, <code>Unspecified</code>. Фильтр по <code>review.severity</code> применяется на стороне коннектора
|-
|review
|string[]
|нет
|<code>Confirmed</code>, <code>Won't fix</code>, <code>False Positive</code>, <code>Unclear</code>
|-
|warnClass
|string[]
|нет
|Идентификатор детектора (<code>DEREF_AFTER_NULL</code>, …)
|-
|file
|string[]
|нет
|Подстрока пути к файлу
|-
|traces
|bool
|нет
|Включить трассы маркеров
|-
|checker_info
|bool
|нет
|Включить метаданные детектора (CWE, описание)
|-
|review_history
|bool
|нет
|Включить историю изменений разметки
|-
|comment_history
|bool
|нет
|Включить комментарии к маркеру
|-
|custom_filter
|string
|нет
|Имя или идентификатор сохранённого фильтра из веб-интерфейса Svacer
|-
|limit
|int
|нет
|Максимальное количество маркеров в ответе (по умолчанию 30). Значение 0 снимает ограничение
|-
|fields
|string[]
|нет
|Список разрешённых полей маркера верхнего уровня. По умолчанию — компактный набор <code>id, warnClass, file, line, msg, function, review</code>. Значение <code>["*"]</code> возвращает все поля коннектора (<code>id, warnClass, file, line, msg, tool, function, mtid, review</code>, а также <code>traces</code>/<code>checkerInfo</code>/<code>review_history</code>/<code>comments</code>, если они запрошены). Допустим и произвольный список, например <code>["id","warnClass"]</code>
|}

'''Вызов:'''
get_markers(
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4",
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",
warnClass=["PROC_USE.VULNERABLE"]
)

'''Ответ:'''
{
"total_count": 341,
"returned_count": 30,
"truncated": true,
"filters_applied": {"warnClass": ["PROC_USE.VULNERABLE"]},
"markers": [
{
"id": "e05bb35b-a95e-4eb2-85ae-3101b788f07d",
"warnClass": "PROC_USE.VULNERABLE.TEMP",
"file": "/.build/lib/sh/tmpfile.c",
"line": 160,
"msg": "Use of vulnerable function 'mktemp' at tmpfile.c:160. ...",
"function": "sh_mktmpname",
"review": null
}
]
}

<code>total_count</code> отражает количество маркеров, удовлетворяющих фильтру до применения ограничения; <code>returned_count</code> — количество маркеров, фактически содержащихся в <code>markers</code>. При <code>truncated: true</code> следует либо сузить фильтры (<code>severity</code>, <code>warnClass</code>, <code>file</code>), либо передать <code>limit=0</code> для получения полного списка. Поля <code>tool</code> и <code>mtid</code> возвращаются только при <code>fields=["*"]</code>.
----

=== get_warnings ===
Полные предупреждения с детальной разметкой. Ответ значительно объёмнее, чем у <code>get_markers</code>, поэтому инструмент следует использовать только тогда, когда нужны поля, отсутствующие в компактной форме: <code>traces</code>, <code>review_history</code>, <code>checker_info</code>, <code>comment_history</code>.

Лимит по умолчанию — 30; при включённых <code>traces</code>, <code>review_history</code> или <code>comment_history</code> он автоматически снижается до 8, поскольку такие предупреждения существенно объёмнее.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|project_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|branch_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|snapshot_id
|string (UUID)
|да
|Из <code>get_snapshots</code>
|-
|severity
|string[]
|нет
|<code>Critical</code>, <code>Major</code>, <code>Minor</code>, <code>Unspecified</code>. Фильтр по <code>review.severity</code>, применяется на стороне коннектора
|-
|review
|string[]
|нет
|<code>Confirmed</code>, <code>Won't fix</code>, <code>False Positive</code>, <code>Unclear</code>
|-
|warnClass
|string[]
|нет
|Идентификатор детектора
|-
|file
|string[]
|нет
|Подстрока пути к файлу
|-
|traces
|bool
|нет
|Включить трассы. Активирует режим расширенных полей (лимит по умолчанию — 8)
|-
|checker_info
|bool
|нет
|Включить метаданные детектора (CWE, описание)
|-
|review_history
|bool
|нет
|Включить историю разметки. Режим расширенных полей
|-
|comment_history
|bool
|нет
|Включить комментарии. Режим расширенных полей
|-
|custom_filter
|string
|нет
|Имя или идентификатор сохранённого фильтра
|-
|limit
|int
|нет
|Максимальное количество предупреждений в ответе. По умолчанию — 30, в режиме расширенных полей — 8. Значение 0 снимает ограничение. Явно заданное <code>limit</code> отменяет автоматическое снижение
|-
|fields
|string[]
|нет
|См. описание в <code>get_markers</code>
|}
'''Вызов:'''
get_warnings(
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4",
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",
severity=["Critical"],
review_history=True,
traces=True
)

'''Ответ:'''
{
"total_count": 1,
"returned_count": 1,
"truncated": false,
"filters_applied": {"severity": ["Critical"], "traces": true, "review_history": true},
"warnings": [
{
"id": "a3f21c90-1d4e-4b82-9f63-7c8e5d2a1b09",
"warnClass": "DEREF_AFTER_NULL.LOOP",
"file": "/.build/execute_cmd.c",
"line": 3327,
"msg": "Possible null pointer dereference of 'l' after loop exit.",
"function": "select_query",
"review": {"status": "Confirmed", "severity": "Critical"},
"review_history": [{"status": "Confirmed", "changed_by": "admin", "changed_at": "2021-12-13T14:00:00Z"}],
"traces": [{"file": "/.build/execute_cmd.c", "line": 3320, "msg": "Loop starts here; 'l' may exhaust the list."}]
}
]
}
----

=== get_diff ===
Сравнение двух снимков. Категории располагаются под ключом <code>markers</code>: <code>new_markers</code> (появилось в новом снимке), <code>missing_markers</code> (исчезло из нового), <code>modified_markers</code> (тот же идентификатор, изменился контекст), <code>matched_markers</code> (совпало в обоих). Параметры <code>project_id</code> и <code>branch_id</code> не требуются — достаточно UUID снимков.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|base_snapshot_id
|string (UUID)
|да
|Старый снимок
|-
|head_snapshot_id
|string (UUID)
|нет
|Новый снимок; если не указан, сравнение выполняется с предыдущим по времени
|-
|level
|int
|нет
|0 — только статистика; 1 — статистика и идентификаторы маркеров; 2 — полные маркеры по категориям
|-
|checker_info
|bool
|нет
|Метаданные детекторов для маркеров (только при <code>level >= 2</code>)
|-
|limit
|int
|нет
|Максимальное количество маркеров '''на каждую категорию''' при <code>level >= 2</code>. По умолчанию — 20, значение 0 снимает ограничение. Параметр игнорируется при <code>level < 2</code>
|-
|fields
|string[]
|нет
|См. описание в <code>get_markers</code>. Применяется к маркерам внутри категорий при <code>level >= 2</code>
|}

'''Вызов (<code>level=0</code>):'''
get_diff(
base_snapshot_id="72b3df7b-c15a-4e3d-8f92-a041dc6e5b87",
head_snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",
level=0
)

'''Ответ (<code>level=0</code>):'''
{
"stats": {
"context1": {"projectName": "paho.mqtt.c", "snapshotName": "Snapshot 2020-03-20 ..."},
"context2": {"projectName": "paho.mqtt.c", "snapshotName": "Snapshot 2020-03-25 ..."},
"scope": ["NEW", "MISSING", "MATCHED", "MODIFIED"],
"new": 9,
"missing": 12,
"modified": 98,
"matched": 187
}
}

'''Ответ (<code>level=2</code>)''' — каждая категория внутри <code>markers</code> оформляется и ограничивается независимо:
{
"stats": {"new": 50, "missing": 5, "modified": 0, "matched": 187},
"markers": {
"new_markers": {
"total_count": 50,
"returned_count": 20,
"truncated": true,
"markers": [
{"id": "a3f21c90-...", "warnClass": "DEREF_AFTER_NULL.LOOP", "file": "...", "line": 3327, "msg": "...", "function": "select_query", "review": null}
]
},
"missing_markers": {"total_count": 5, "returned_count": 5, "truncated": false, "markers": [...]},
"modified_markers": {"total_count": 0, "returned_count": 0, "truncated": false, "markers": []},
"matched_markers": {"total_count": 187, "returned_count": 20, "truncated": true, "markers": [...]}
}
}

Если требуется полное содержимое категории, следует увеличить <code>limit</code>, либо запросить нужные идентификаторы отдельным вызовом <code>get_markers</code>. Маркеры внутри категорий проходят ту же компактную обработку, что и в <code>get_warnings</code>: значение <code>fields=["*"]</code> возвращает фиксированный набор полей коннектора, а не произвольные «сырые» поля API.
----

=== get_advanced_file_preview ===
Фрагмент исходного кода из снимка вокруг указанной строки. Параметры <code>project_id</code> и <code>branch_id</code> не требуются — достаточно идентификатора снимка и пути к файлу.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|snapshot_id
|string (UUID)
|да
|UUID снимка
|-
|file_path
|string
|да
|Путь к файлу в том виде, в котором его возвращают <code>get_markers</code> и <code>get_warnings</code>
|-
|line
|int
|нет
|Центральная строка, нумерация с 1 (по умолчанию 1)
|-
|before
|int
|нет
|Количество строк до центральной (по умолчанию 0)
|-
|after
|int
|нет
|Количество строк после центральной (по умолчанию 99999 — до конца файла)
|}

'''Вызов:'''
get_advanced_file_preview(
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",
file_path="/.build/execute_cmd.c",
line=3327,
before=10,
after=10
)

'''Ответ:'''
{
"line": 3327,
"content": " for (l = list; l && --reply; l = l->next)\n\t;\n return (l->word->word);\n",
"total_lines": 6082
}
----

=== get_project_groups ===
Получить группу проектов по имени или UUID. Группы объединяют проекты в логические блоки — например, по команде или продукту.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|name_or_id
|string
|да
|Имя группы или её UUID
|}

'''Вызов:'''
get_project_groups(name_or_id="Linux Tools")

'''Ответ:'''
{
"project_group_id": "c4f8a2d1-3b7e-4f90-82ac-1d5e8f2b6c04",
"project_group_name": "Linux Tools",
"projects": [
{"id": "91630e84-db2f-4d8c-8716-68b7fdf17a66", "name": "bash"},
{"id": "d3a17f52-...", "name": "coreutils"}
]
}

<code>projects[].id</code> — это <code>project_id</code>, который далее передаётся в <code>get_snapshots</code>. Группы и проекты — разные сущности; идентификатор группы и идентификатор проекта не взаимозаменяемы.

== Примеры сценариев ==
Приведённые ниже запросы выполнены на демонстрационном стенде <code>svacer-demo.ispras.ru</code> с использованием OpenWebUI и модели <code>qwen3-coder:30b</code>. В любом другом MCP-клиенте с моделью достаточной мощности порядок вызовов будет аналогичным.

=== Про объём ответа ===
<code>get_markers</code>, <code>get_warnings</code> и <code>get_diff(level=2)</code> по умолчанию ограничивают объём ответа, чтобы не перегружать контекст модели:

* <code>get_markers</code> и <code>get_warnings</code> — 30 маркеров по умолчанию. Если у <code>get_warnings</code> включены <code>traces</code>, <code>review_history</code> или <code>comment_history</code>, лимит снижается до 8, поскольку такие маркеры значительно объёмнее.
* <code>get_diff(level=2)</code> — 20 маркеров на каждую категорию внутри <code>markers</code> (<code>new_markers</code>/<code>missing_markers</code>/<code>modified_markers</code>/<code>matched_markers</code>).

В ответе присутствуют поля <code>total_count</code>, <code>returned_count</code>, <code>truncated</code>. При <code>truncated: true</code> есть два варианта действий: сузить фильтр (<code>severity</code>, <code>warnClass</code>, <code>file</code>) либо явно увеличить <code>limit</code> (значение <code>limit=0</code> полностью снимает ограничение).

Поле <code>fields</code> определяет, какие ключи маркера возвращаются. По умолчанию применяется компактный набор <code>id, warnClass, file, line, msg, function, review</code> (а также <code>traces</code>/<code>checkerInfo</code>/<code>review_history</code>/<code>comments</code>, если они запрошены логическими флагами и пришли с сервера). Для полного маркера со всеми служебными ключами — <code>fields=["*"]</code>. Для произвольной выборки — список полей верхнего уровня, например <code>fields=["id","warnClass"]</code>. Поле <code>review</code> — объект <code>{status, severity, action}</code>; вложенные ключи в <code>fields</code> не поддерживаются, поэтому объект <code>review</code> запрашивается целиком.

=== Перечислить все проекты ===
<blockquote>Какие проекты есть в Svacer?</blockquote>

'''Цепочка вызовов:'''
# <code>get_projects()</code>

'''Ответ модели:'''
<blockquote>В Svacer доступно 6 проектов: bash, openssl, paho.mqtt.c, coturn, zstd, darpa. У каждого — одна ветка <code>master</code>.</blockquote>

=== Посмотреть снимки проекта ===
<blockquote>Какие снимки есть у paho.mqtt.c? Самый свежий когда?</blockquote>'''Цепочка вызовов:'''

# <code>get_projects()</code> — найти <code>project_id</code> и <code>branch_id</code>
# <code>get_snapshots(project_id=..., branch_id=...)</code>

'''Ответ модели:'''
<blockquote>У paho.mqtt.c 3 снимка. Самый свежий — «Snapshot 2020-03-25 09:09:41 +0300» (297 маркеров). Предыдущий — 20 марта (306 маркеров).</blockquote>Поле <code>commit_hash</code> может принимать значение <code>null</code>, если проект не сохраняет хэш коммита в <code>custom_properties</code>. Имена снимков произвольны: одни проекты записывают в имя дату, другие — коммит, третьи — свободный текст.

=== Сводка по проекту ===
<blockquote>Что в bash в последнем снимке? Сколько всего предупреждений, есть ли критические, какие топ-детекторы?</blockquote>

'''Цепочка вызовов:'''
# <code>get_projects()</code>
# <code>get_snapshots(project_id, branch_id)</code> — взять последний снимок
# <code>get_project_stats(project_id, branch_id, snapshot_id)</code>

'''Ответ модели:'''
<blockquote>В последнем снимке bash содержится 771 предупреждение:

* Критических: 1 (Confirmed)
* Major: 1 (Won't fix)
* Остальные: 769 (Unspecified — не размечались)

Топ-детекторы по количеству:

# <code>PROC_USE.VULNERABLE</code> — 337
# <code>UNUSED_FUNC_RES.REWRITE.MINOR</code> — 44
# <code>UNREACHABLE_CODE</code> — 28
# <code>DEREF_AFTER_NULL.EX</code> — 27
# <code>NULL_AFTER_DEREF</code> — 27
</blockquote>

<code>Unspecified</code> в <code>by_severity</code> — маркеры без ручной разметки, а не «низкий приоритет». Поле <code>by_checker</code> не сортируется, на большом снимке оно может содержать более 100 ключей — чтобы получить именно топ-N, следует явно сформулировать запрос: «топ-5 детекторов».

=== Тренд по нескольким снимкам ===
<blockquote>Как у openssl менялось число предупреждений за последние пять снимков? Покажи таблицей.</blockquote>

'''Цепочка вызовов:'''

# <code>get_projects()</code>
# <code>get_snapshots()</code> — взять список
# <code>get_project_stats()</code> × 5 — по каждому из последних пяти снимков

'''Ответ модели:'''
<blockquote>
{| class="wikitable"
|+
!Снимок
!Дата
!Всего
|-
|2020-04-30 05:49
|30.04.2020
|1252
|-
|2020-04-30 05:29
|30.04.2020
|1252
|-
|2020-04-30 05:08
|30.04.2020
|1252
|-
|2020-04-30 04:48
|30.04.2020
|1252
|-
|2020-04-30 04:22
|30.04.2020
|1252
|}
</blockquote>

На демонстрационном стенде указанные пять снимков openssl импортированы с интервалом в 20 минут одного дня и полностью идентичны — поэтому динамика отсутствует. На реальном проекте с историей релизов значения будут изменяться.

=== Найти срабатывания конкретного детектора ===
<blockquote>Где в bash срабатывает PROC_USE.VULNERABLE? Покажи список — файл, строка, что именно ругается. Достаточно первых десяти.</blockquote>

'''Цепочка вызовов:'''
# <code>get_projects()</code>
# <code>get_snapshots()</code>
# <code>get_markers(warnClass=["PROC_USE.VULNERABLE"])</code>

'''Ответ модели:'''
<blockquote>
# <code>/.build/lib/sh/tmpfile.c:160</code> — <code>mktemp()</code>, race condition. Рекомендуется <code>mkstemp()</code>.
# <code>/.build/lib/readline/shell.c:151</code> — <code>getenv()</code>, значение может быть подменено.
# <code>/.build/shell.c:415</code> — <code>getenv()</code> в <code>main()</code>.
# <code>/.build/lib/readline/complete.c:1516</code> — <code>getenv()</code>.
# <code>/.build/lib/sh/eaccess.c:115</code> — <code>strcat()</code>, рекомендуется <code>strncat()</code>.
</blockquote>

Фильтр <code>warnClass=["PROC_USE.VULNERABLE"]</code> охватывает все подклассы: <code>PROC_USE.VULNERABLE.TEMP</code>, <code>.GETENV</code>, <code>.STRCAT</code> и т. д. — всего 341 маркер. Несколько значений в одном параметре трактуются как логическое «ИЛИ»: <code>severity=["Critical","Major"]</code> возвращает маркеры обеих категорий.

В ответе будет <code>total_count: 341, returned_count: 30, truncated: true</code> — это ожидаемое поведение. Модель видит общий объём по <code>total_count</code> и при необходимости сужает запрос или вызывает <code>get_markers(..., limit=0)</code>, чтобы получить полный список.

=== Сравнить два снимка ===
<blockquote>Возьми два последних снимка paho.mqtt.c — что между ними изменилось? Сколько новых предупреждений, сколько починили?</blockquote>

'''Цепочка вызовов:'''
# <code>get_projects()</code>
# <code>get_snapshots()</code> — два последних
# <code>get_diff(base_snapshot_id="72b3df7b-...", head_snapshot_id="b42cb563-...", level=0)</code>

'''Ответ модели:'''
<blockquote>Между двумя последними снимками paho.mqtt.c:

* Новых: 12
* Удалённых: 13
* Изменённых: 99
* Совпадающих: 185

Удалено несколько больше, чем добавлено — общая картина практически не изменилась.</blockquote>

Категория <code>modified</code> — маркер, присутствующий в обоих снимках, у которого изменилось окружение (номер строки, контекст функции). Это не новая ошибка. На больших проектах рекомендуется начинать с <code>level=0</code> для получения статистики, при необходимости использовать <code>level=1</code> (только идентификаторы маркеров) и затем точечно вызывать <code>get_markers</code> с нужными фильтрами.

<code>level=2</code> возвращает полные маркеры по категориям, причём каждая категория по умолчанию ограничена 20 маркерами. Категории располагаются внутри <code>markers</code>: <code>new_markers</code>, <code>missing_markers</code>, <code>modified_markers</code>, <code>matched_markers</code>. Структура ответа в JSON: <code><nowiki>{"markers": {"new_markers": {"total_count": N, "returned_count": ..., "truncated": ..., "markers": [...]}, ...}}</nowiki></code>. Если требуется полное содержимое категории, следует увеличить <code>limit</code> или выполнить отдельный вызов <code>get_markers</code> по нужным идентификаторам.

=== Разобрать конкретное предупреждение ===
<blockquote>В bash есть один подтверждённый критикал — что-то про разыменование указателя. Покажи код вокруг этого места и объясни в чём проблема.</blockquote>

'''Цепочка вызовов:'''
# <code>get_projects()</code> → <code>get_snapshots()</code> — найти снимок bash
# <code>get_markers(severity=["Critical"], review=["Confirmed"])</code>
# <code>get_advanced_file_preview(file_path="/.build/execute_cmd.c", line=3327, before=10, after=10)</code>

'''Ответ модели:'''
<blockquote>Маркер <code>DEREF_AFTER_NULL.LOOP</code> в функции <code>select_query()</code>, строка 3327:
<code>for (l = list; l && --reply; l = l->next)

;

return (l->word->word); /* l может быть NULL после выхода из цикла */</code>

Если список заканчивается раньше, чем <code>reply</code> обнуляется, <code>l</code> станет <code>NULL</code> на последнем <code>l->next</code>, и следующий <code>l->word->word</code> — разыменование нулевого указателя.</blockquote><code>file_path</code> должен точно совпадать со значением, возвращённым маркером, включая ведущий префикс <code>/.build/...</code>. Это путь внутри сборочной директории Svacer, а не путь в исходном репозитории; соответствие в репозитории определяется по имени файла.

Для одиночной разметки удобно сразу запрашивать полный маркер с трассами: <code>get_markers(..., severity=["Critical"], review=["Confirmed"], traces=True, checker_info=True)</code>. Флаги <code>traces</code> и <code>checker_info</code> указывают серверу включить соответствующие поля в ответ; в выдаче они сохраняются и при значении <code>fields</code> по умолчанию. Значение <code>fields=["*"]</code> требуется лишь в том случае, когда дополнительно нужны <code>tool</code> и <code>mtid</code> — служебные ключи, исключённые из компактного набора.

Help:13-alpha MCP

2026-05-26T10:31:53Z

Vaclovas:

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

[[File:Архитектура MCP.png|thumb|none|x800px|alt=architectureMCP|Архитектура MCP-сервера]]

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

== Установка ==

Svacer MCP может быть подключён к любому серверу Svacer версии 12 и выше. В данном разделе описывается установка Svacer MCP, подключение клиентов и конфигурация.

<code>git clone <nowiki>https://gitlab.ispras.ru/vaclovas/svacermcp.git</nowiki> && cd svacermcp</code><br>

<code>python3 -m venv .venv</code> <br>

<code>.venv/bin/pip install -e .</code>

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

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

=== Режим STDIO ===
Подходит для настольных клиентов: Claude Desktop, Claude Code, Cursor, VS Code.
cp .env.example .env
# Отредактировать .env — указать URL и учётные данные Svacer

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

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

=== Режим 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: <nowiki>http://localhost:8002/mcp</nowiki>
# Клиенты передают заголовок: Authorization: Bearer <SVACER_MCP_TOKEN>

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

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

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

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

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

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

==== VS Code ====
Файл <code>.vscode/mcp.json</code> в корне рабочей директории:

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

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

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

==== OpenWebUI ====
# Развернуть через Docker (см. [[Help:13-alpha MCP#Режим HTTP (Docker)|Режим HTTP]]).
# Открыть '''Settings → Tools''' (или '''Admin Panel → Settings → Tools''').
# Добавить сервер:
#* <code><nowiki>http://localhost:8002/mcp</nowiki></code> — если OpenWebUI работает на хосте, снаружи Docker.
#* <code><nowiki>http://svacer-mcp:8000/mcp</nowiki></code> — если OpenWebUI развёрнут в той же compose-сети, что и <code>svacer-mcp</code> (имя берётся из <code>docker-compose.yml</code> → service name, порт 8000 — внутренний порт контейнера).
# Тип подключения: '''MCP (Streamable HTTP)'''.
# В настройках инструмента указать заголовок <code>Authorization: Bearer <SVACER_MCP_TOKEN></code> (значение — то же, что в <code>.env</code> сервера).
# Сохранить — инструменты появятся в чате.

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

==== Ограничение набора инструментов ====
Чтобы запустить сервер с подмножеством инструментов (например, для уменьшения объёма контекста у модели или разграничения доступа), задайте <code>SVACER_TOOLS</code>:
SVACER_TOOLS=get_projects,get_snapshots,get_markers
Допустимые имена: <code>get_projects</code>, <code>get_snapshots</code>, <code>get_warnings</code>, <code>get_markers</code>, <code>get_project_stats</code>, <code>get_project_groups</code>, <code>get_advanced_file_preview</code>, <code>get_diff</code>. Неизвестное имя в списке приводит к ошибке при запуске. Если переменная пустая или не задана, регистрируются все 8 инструментов.

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

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

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

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

==== Передача токена клиентом ====
Большинство HTTP-клиентов MCP (OpenWebUI и др.) позволяют задать произвольный заголовок <code>Authorization</code> в настройках инструмента — указывается значение <code>Bearer <токен></code>. Для ручной проверки:
curl -H "Authorization: Bearer $SVACER_MCP_TOKEN" \
<nowiki> </nowiki> -H 'Content-Type: application/json' \
<nowiki> </nowiki> -H 'Accept: application/json, text/event-stream' \
<nowiki> </nowiki> -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' \
<nowiki> </nowiki> <nowiki>http://localhost:8002/mcp</nowiki>

== Инструменты ==
Справочник по 8 инструментам Svacer MCP. Типичный порядок вызовов: <code>get_projects</code> → <code>get_snapshots</code> → любой из аналитических инструментов.
{| class="wikitable"
!Инструмент
!Назначение
|-
|get_projects
|Список проектов с ветками — точка входа
|-
|get_snapshots
|Снимки конкретной ветки, от нового к старому
|-
|get_project_stats
|Агрегированные метрики снимка: severity / review / checker
|-
|get_markers
|Компактный список маркеров с серверной фильтрацией
|-
|get_warnings
|Полные предупреждения с трассами и историей разметки
|-
|get_diff
|Сравнение двух снимков: new / missing / modified / matched
|-
|get_advanced_file_preview
|Фрагмент исходного кода вокруг строки
|-
|get_project_groups
|Группа проектов по имени или UUID
|}

=== get_projects ===
Список всех проектов с ветками. Точка входа: с этого вызова начинается практически любой сценарий — он возвращает <code>project_id</code> и <code>branch_id</code>, необходимые для последующих запросов.

'''Параметров нет.'''

'''Вызов:'''
get_projects()

'''Ответ:'''
[
{
"project_id": "91630e84-db2f-4d8c-8716-68b7fdf17a66",
"project_name": "bash",
"created": "2021-12-13T13:22:42.122456Z",
"created_by": "admin",
"branches": [
{
"branch_id": "77f66b9e-0453-4ae9-a187-88950b4c4bc4",
"branch_name": "master",
"created": "2021-12-13T13:22:42.394812Z"
}
]
}
]
----

=== get_snapshots ===
Список снимков для конкретной ветки проекта, от нового к старому.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|project_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|branch_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|name_filter
|string
|нет
|Подстрока или regex для фильтра по имени снимка
|}

'''Вызов:'''
get_snapshots(
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4"
)

'''Ответ:'''
[
{
"snapshot_id": "b42cb563-86f4-4f96-900a-7782163327c9",
"name": "Snapshot 2020-03-25 09:09:41 +0300",
"import_time": "2020-03-25T09:09:41.837296Z",
"commit_hash": null,
"markers_count": 297,
"link": "<nowiki>https://svacer-demo.ispras.ru/</nowiki>..."
}
]
----

=== get_project_stats ===
Агрегированные метрики по снимку: общее количество предупреждений, распределение по критичности, по статусу разметки, по детекторам. Наиболее быстрый способ получить общую картину по проекту.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|project_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|branch_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|snapshot_id
|string (UUID)
|да
|Из <code>get_snapshots</code>
|}

'''Вызов:'''
get_project_stats(
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4",
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9"
)

'''Ответ:'''
{
"total_warnings": 771,
"by_severity": {
"Critical": 1,
"Major": 1,
"Unspecified": 769
},
"by_review_status": {
"Confirmed": 1,
"False Positive": 1,
"Undecided": 767,
"Unclear": 1,
"Won't fix": 1
},
"by_checker": {
"PROC_USE.VULNERABLE": 337,
"UNUSED_FUNC_RES.REWRITE.MINOR": 44,
"UNREACHABLE_CODE": 28,
"DEREF_AFTER_NULL.EX": 27,
"NULL_AFTER_DEREF": 27
}
}
----

=== get_markers ===
Компактный список маркеров с серверной фильтрацией. Основной инструмент для перечисления и обзора: его следует предпочитать <code>get_warnings</code>, когда не требуются развёрнутые поля — трассы и история разметки.

По умолчанию ответ ограничен 30 маркерами и содержит компактный набор полей. Подробнее об ограничении объёма см. раздел [[Help:13-alpha MCP#Про объём ответа|Про объём ответа]].

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|project_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|branch_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|snapshot_id
|string (UUID)
|да
|Из <code>get_snapshots</code>
|-
|severity
|string[]
|нет
|<code>Critical</code>, <code>Major</code>, <code>Minor</code>, <code>Unspecified</code>. Фильтр по <code>review.severity</code> применяется на стороне коннектора
|-
|review
|string[]
|нет
|<code>Confirmed</code>, <code>Won't fix</code>, <code>False Positive</code>, <code>Unclear</code>
|-
|warnClass
|string[]
|нет
|Идентификатор детектора (<code>DEREF_AFTER_NULL</code>, …)
|-
|file
|string[]
|нет
|Подстрока пути к файлу
|-
|traces
|bool
|нет
|Включить трассы маркеров
|-
|checker_info
|bool
|нет
|Включить метаданные детектора (CWE, описание)
|-
|review_history
|bool
|нет
|Включить историю изменений разметки
|-
|comment_history
|bool
|нет
|Включить комментарии к маркеру
|-
|custom_filter
|string
|нет
|Имя или идентификатор сохранённого фильтра из веб-интерфейса Svacer
|-
|limit
|int
|нет
|Максимальное количество маркеров в ответе (по умолчанию 30). Значение 0 снимает ограничение
|-
|fields
|string[]
|нет
|Список разрешённых полей маркера верхнего уровня. По умолчанию — компактный набор <code>id, warnClass, file, line, msg, function, review</code>. Значение <code>["*"]</code> возвращает все поля коннектора (<code>id, warnClass, file, line, msg, tool, function, mtid, review</code>, а также <code>traces</code>/<code>checkerInfo</code>/<code>review_history</code>/<code>comments</code>, если они запрошены). Допустим и произвольный список, например <code>["id","warnClass"]</code>
|}

'''Вызов:'''
get_markers(
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4",
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",
warnClass=["PROC_USE.VULNERABLE"]
)

'''Ответ:'''
{
"total_count": 341,
"returned_count": 30,
"truncated": true,
"filters_applied": {"warnClass": ["PROC_USE.VULNERABLE"]},
"markers": [
{
"id": "e05bb35b-a95e-4eb2-85ae-3101b788f07d",
"warnClass": "PROC_USE.VULNERABLE.TEMP",
"file": "/.build/lib/sh/tmpfile.c",
"line": 160,
"msg": "Use of vulnerable function 'mktemp' at tmpfile.c:160. ...",
"function": "sh_mktmpname",
"review": null
}
]
}

<code>total_count</code> отражает количество маркеров, удовлетворяющих фильтру до применения ограничения; <code>returned_count</code> — количество маркеров, фактически содержащихся в <code>markers</code>. При <code>truncated: true</code> следует либо сузить фильтры (<code>severity</code>, <code>warnClass</code>, <code>file</code>), либо передать <code>limit=0</code> для получения полного списка. Поля <code>tool</code> и <code>mtid</code> возвращаются только при <code>fields=["*"]</code>.
----

=== get_warnings ===
Полные предупреждения с детальной разметкой. Ответ значительно объёмнее, чем у <code>get_markers</code>, поэтому инструмент следует использовать только тогда, когда нужны поля, отсутствующие в компактной форме: <code>traces</code>, <code>review_history</code>, <code>checker_info</code>, <code>comment_history</code>.

Лимит по умолчанию — 30; при включённых <code>traces</code>, <code>review_history</code> или <code>comment_history</code> он автоматически снижается до 8, поскольку такие предупреждения существенно объёмнее.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|project_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|branch_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|snapshot_id
|string (UUID)
|да
|Из <code>get_snapshots</code>
|-
|severity
|string[]
|нет
|<code>Critical</code>, <code>Major</code>, <code>Minor</code>, <code>Unspecified</code>. Фильтр по <code>review.severity</code>, применяется на стороне коннектора
|-
|review
|string[]
|нет
|<code>Confirmed</code>, <code>Won't fix</code>, <code>False Positive</code>, <code>Unclear</code>
|-
|warnClass
|string[]
|нет
|Идентификатор детектора
|-
|file
|string[]
|нет
|Подстрока пути к файлу
|-
|traces
|bool
|нет
|Включить трассы. Активирует режим расширенных полей (лимит по умолчанию — 8)
|-
|checker_info
|bool
|нет
|Включить метаданные детектора (CWE, описание)
|-
|review_history
|bool
|нет
|Включить историю разметки. Режим расширенных полей
|-
|comment_history
|bool
|нет
|Включить комментарии. Режим расширенных полей
|-
|custom_filter
|string
|нет
|Имя или идентификатор сохранённого фильтра
|-
|limit
|int
|нет
|Максимальное количество предупреждений в ответе. По умолчанию — 30, в режиме расширенных полей — 8. Значение 0 снимает ограничение. Явно заданное <code>limit</code> отменяет автоматическое снижение
|-
|fields
|string[]
|нет
|См. описание в <code>get_markers</code>
|}
'''Вызов:'''
get_warnings(
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4",
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",
severity=["Critical"],
review_history=True,
traces=True
)

'''Ответ:'''
{
"total_count": 1,
"returned_count": 1,
"truncated": false,
"filters_applied": {"severity": ["Critical"], "traces": true, "review_history": true},
"warnings": [
{
"id": "a3f21c90-1d4e-4b82-9f63-7c8e5d2a1b09",
"warnClass": "DEREF_AFTER_NULL.LOOP",
"file": "/.build/execute_cmd.c",
"line": 3327,
"msg": "Possible null pointer dereference of 'l' after loop exit.",
"function": "select_query",
"review": {"status": "Confirmed", "severity": "Critical"},
"review_history": [{"status": "Confirmed", "changed_by": "admin", "changed_at": "2021-12-13T14:00:00Z"}],
"traces": [{"file": "/.build/execute_cmd.c", "line": 3320, "msg": "Loop starts here; 'l' may exhaust the list."}]
}
]
}
----

=== get_diff ===
Сравнение двух снимков. Категории располагаются под ключом <code>markers</code>: <code>new_markers</code> (появилось в новом снимке), <code>missing_markers</code> (исчезло из нового), <code>modified_markers</code> (тот же идентификатор, изменился контекст), <code>matched_markers</code> (совпало в обоих). Параметры <code>project_id</code> и <code>branch_id</code> не требуются — достаточно UUID снимков.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|base_snapshot_id
|string (UUID)
|да
|Старый снимок
|-
|head_snapshot_id
|string (UUID)
|нет
|Новый снимок; если не указан, сравнение выполняется с предыдущим по времени
|-
|level
|int
|нет
|0 — только статистика; 1 — статистика и идентификаторы маркеров; 2 — полные маркеры по категориям
|-
|checker_info
|bool
|нет
|Метаданные детекторов для маркеров (только при <code>level >= 2</code>)
|-
|limit
|int
|нет
|Максимальное количество маркеров '''на каждую категорию''' при <code>level >= 2</code>. По умолчанию — 20, значение 0 снимает ограничение. Параметр игнорируется при <code>level < 2</code>
|-
|fields
|string[]
|нет
|См. описание в <code>get_markers</code>. Применяется к маркерам внутри категорий при <code>level >= 2</code>
|}

'''Вызов (<code>level=0</code>):'''
get_diff(
base_snapshot_id="72b3df7b-c15a-4e3d-8f92-a041dc6e5b87",
head_snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",
level=0
)

'''Ответ (<code>level=0</code>):'''
{
"stats": {
"context1": {"projectName": "paho.mqtt.c", "snapshotName": "Snapshot 2020-03-20 ..."},
"context2": {"projectName": "paho.mqtt.c", "snapshotName": "Snapshot 2020-03-25 ..."},
"scope": ["NEW", "MISSING", "MATCHED", "MODIFIED"],
"new": 9,
"missing": 12,
"modified": 98,
"matched": 187
}
}

'''Ответ (<code>level=2</code>)''' — каждая категория внутри <code>markers</code> оформляется и ограничивается независимо:
{
"stats": {"new": 50, "missing": 5, "modified": 0, "matched": 187},
"markers": {
"new_markers": {
"total_count": 50,
"returned_count": 20,
"truncated": true,
"markers": [
{"id": "a3f21c90-...", "warnClass": "DEREF_AFTER_NULL.LOOP", "file": "...", "line": 3327, "msg": "...", "function": "select_query", "review": null}
]
},
"missing_markers": {"total_count": 5, "returned_count": 5, "truncated": false, "markers": [...]},
"modified_markers": {"total_count": 0, "returned_count": 0, "truncated": false, "markers": []},
"matched_markers": {"total_count": 187, "returned_count": 20, "truncated": true, "markers": [...]}
}
}

Если требуется полное содержимое категории, следует увеличить <code>limit</code>, либо запросить нужные идентификаторы отдельным вызовом <code>get_markers</code>. Маркеры внутри категорий проходят ту же компактную обработку, что и в <code>get_warnings</code>: значение <code>fields=["*"]</code> возвращает фиксированный набор полей коннектора, а не произвольные «сырые» поля API.
----

=== get_advanced_file_preview ===
Фрагмент исходного кода из снимка вокруг указанной строки. Параметры <code>project_id</code> и <code>branch_id</code> не требуются — достаточно идентификатора снимка и пути к файлу.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|snapshot_id
|string (UUID)
|да
|UUID снимка
|-
|file_path
|string
|да
|Путь к файлу в том виде, в котором его возвращают <code>get_markers</code> и <code>get_warnings</code>
|-
|line
|int
|нет
|Центральная строка, нумерация с 1 (по умолчанию 1)
|-
|before
|int
|нет
|Количество строк до центральной (по умолчанию 0)
|-
|after
|int
|нет
|Количество строк после центральной (по умолчанию 99999 — до конца файла)
|}

'''Вызов:'''
get_advanced_file_preview(
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",
file_path="/.build/execute_cmd.c",
line=3327,
before=10,
after=10
)

'''Ответ:'''
{
"line": 3327,
"content": " for (l = list; l && --reply; l = l->next)\n\t;\n return (l->word->word);\n",
"total_lines": 6082
}
----

=== get_project_groups ===
Получить группу проектов по имени или UUID. Группы объединяют проекты в логические блоки — например, по команде или продукту.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|name_or_id
|string
|да
|Имя группы или её UUID
|}

'''Вызов:'''
get_project_groups(name_or_id="Linux Tools")

'''Ответ:'''
{
"project_group_id": "c4f8a2d1-3b7e-4f90-82ac-1d5e8f2b6c04",
"project_group_name": "Linux Tools",
"projects": [
{"id": "91630e84-db2f-4d8c-8716-68b7fdf17a66", "name": "bash"},
{"id": "d3a17f52-...", "name": "coreutils"}
]
}

<code>projects[].id</code> — это <code>project_id</code>, который далее передаётся в <code>get_snapshots</code>. Группы и проекты — разные сущности; идентификатор группы и идентификатор проекта не взаимозаменяемы.

== Примеры сценариев ==
Приведённые ниже запросы выполнены на демонстрационном стенде <code>svacer-demo.ispras.ru</code> с использованием OpenWebUI и модели <code>qwen3-coder:30b</code>. В любом другом MCP-клиенте с моделью достаточной мощности порядок вызовов будет аналогичным.

=== Про объём ответа ===
<code>get_markers</code>, <code>get_warnings</code> и <code>get_diff(level=2)</code> по умолчанию ограничивают объём ответа, чтобы не перегружать контекст модели:

* <code>get_markers</code> и <code>get_warnings</code> — 30 маркеров по умолчанию. Если у <code>get_warnings</code> включены <code>traces</code>, <code>review_history</code> или <code>comment_history</code>, лимит снижается до 8, поскольку такие маркеры значительно объёмнее.
* <code>get_diff(level=2)</code> — 20 маркеров на каждую категорию внутри <code>markers</code> (<code>new_markers</code>/<code>missing_markers</code>/<code>modified_markers</code>/<code>matched_markers</code>).

В ответе присутствуют поля <code>total_count</code>, <code>returned_count</code>, <code>truncated</code>. При <code>truncated: true</code> есть два варианта действий: сузить фильтр (<code>severity</code>, <code>warnClass</code>, <code>file</code>) либо явно увеличить <code>limit</code> (значение <code>limit=0</code> полностью снимает ограничение).

Поле <code>fields</code> определяет, какие ключи маркера возвращаются. По умолчанию применяется компактный набор <code>id, warnClass, file, line, msg, function, review</code> (а также <code>traces</code>/<code>checkerInfo</code>/<code>review_history</code>/<code>comments</code>, если они запрошены логическими флагами и пришли с сервера). Для полного маркера со всеми служебными ключами — <code>fields=["*"]</code>. Для произвольной выборки — список полей верхнего уровня, например <code>fields=["id","warnClass"]</code>. Поле <code>review</code> — объект <code>{status, severity, action}</code>; вложенные ключи в <code>fields</code> не поддерживаются, поэтому объект <code>review</code> запрашивается целиком.

=== Перечислить все проекты ===
<blockquote>Какие проекты есть в Svacer?</blockquote>

'''Цепочка вызовов:'''
# <code>get_projects()</code>

'''Ответ модели:'''
<blockquote>В Svacer доступно 6 проектов: bash, openssl, paho.mqtt.c, coturn, zstd, darpa. У каждого — одна ветка <code>master</code>.</blockquote>

=== Посмотреть снимки проекта ===
<blockquote>Какие снимки есть у paho.mqtt.c? Самый свежий когда?</blockquote>'''Цепочка вызовов:'''

# <code>get_projects()</code> — найти <code>project_id</code> и <code>branch_id</code>
# <code>get_snapshots(project_id=..., branch_id=...)</code>

'''Ответ модели:'''
<blockquote>У paho.mqtt.c 3 снимка. Самый свежий — «Snapshot 2020-03-25 09:09:41 +0300» (297 маркеров). Предыдущий — 20 марта (306 маркеров).</blockquote>Поле <code>commit_hash</code> может принимать значение <code>null</code>, если проект не сохраняет хэш коммита в <code>custom_properties</code>. Имена снимков произвольны: одни проекты записывают в имя дату, другие — коммит, третьи — свободный текст.

=== Сводка по проекту ===
<blockquote>Что в bash в последнем снимке? Сколько всего предупреждений, есть ли критические, какие топ-детекторы?</blockquote>

'''Цепочка вызовов:'''
# <code>get_projects()</code>
# <code>get_snapshots(project_id, branch_id)</code> — взять последний снимок
# <code>get_project_stats(project_id, branch_id, snapshot_id)</code>

'''Ответ модели:'''
<blockquote>В последнем снимке bash содержится 771 предупреждение:

* Критических: 1 (Confirmed)
* Major: 1 (Won't fix)
* Остальные: 769 (Unspecified — не размечались)

Топ-детекторы по количеству:

# <code>PROC_USE.VULNERABLE</code> — 337
# <code>UNUSED_FUNC_RES.REWRITE.MINOR</code> — 44
# <code>UNREACHABLE_CODE</code> — 28
# <code>DEREF_AFTER_NULL.EX</code> — 27
# <code>NULL_AFTER_DEREF</code> — 27
</blockquote>

<code>Unspecified</code> в <code>by_severity</code> — маркеры без ручной разметки, а не «низкий приоритет». Поле <code>by_checker</code> не сортируется, на большом снимке оно может содержать более 100 ключей — чтобы получить именно топ-N, следует явно сформулировать запрос: «топ-5 детекторов».

=== Тренд по нескольким снимкам ===
<blockquote>Как у openssl менялось число предупреждений за последние пять снимков? Покажи таблицей.</blockquote>

'''Цепочка вызовов:'''

# <code>get_projects()</code>
# <code>get_snapshots()</code> — взять список
# <code>get_project_stats()</code> × 5 — по каждому из последних пяти снимков

'''Ответ модели:'''
<blockquote>
{| class="wikitable"
|+
!Снимок
!Дата
!Всего
|-
|2020-04-30 05:49
|30.04.2020
|1252
|-
|2020-04-30 05:29
|30.04.2020
|1252
|-
|2020-04-30 05:08
|30.04.2020
|1252
|-
|2020-04-30 04:48
|30.04.2020
|1252
|-
|2020-04-30 04:22
|30.04.2020
|1252
|}
</blockquote>

На демонстрационном стенде указанные пять снимков openssl импортированы с интервалом в 20 минут одного дня и полностью идентичны — поэтому динамика отсутствует. На реальном проекте с историей релизов значения будут изменяться.

=== Найти срабатывания конкретного детектора ===
<blockquote>Где в bash срабатывает PROC_USE.VULNERABLE? Покажи список — файл, строка, что именно ругается. Достаточно первых десяти.</blockquote>

'''Цепочка вызовов:'''
# <code>get_projects()</code>
# <code>get_snapshots()</code>
# <code>get_markers(warnClass=["PROC_USE.VULNERABLE"])</code>

'''Ответ модели:'''
<blockquote>
# <code>/.build/lib/sh/tmpfile.c:160</code> — <code>mktemp()</code>, race condition. Рекомендуется <code>mkstemp()</code>.
# <code>/.build/lib/readline/shell.c:151</code> — <code>getenv()</code>, значение может быть подменено.
# <code>/.build/shell.c:415</code> — <code>getenv()</code> в <code>main()</code>.
# <code>/.build/lib/readline/complete.c:1516</code> — <code>getenv()</code>.
# <code>/.build/lib/sh/eaccess.c:115</code> — <code>strcat()</code>, рекомендуется <code>strncat()</code>.
</blockquote>

Фильтр <code>warnClass=["PROC_USE.VULNERABLE"]</code> охватывает все подклассы: <code>PROC_USE.VULNERABLE.TEMP</code>, <code>.GETENV</code>, <code>.STRCAT</code> и т. д. — всего 341 маркер. Несколько значений в одном параметре трактуются как логическое «ИЛИ»: <code>severity=["Critical","Major"]</code> возвращает маркеры обеих категорий.

В ответе будет <code>total_count: 341, returned_count: 30, truncated: true</code> — это ожидаемое поведение. Модель видит общий объём по <code>total_count</code> и при необходимости сужает запрос или вызывает <code>get_markers(..., limit=0)</code>, чтобы получить полный список.

=== Сравнить два снимка ===
<blockquote>Возьми два последних снимка paho.mqtt.c — что между ними изменилось? Сколько новых предупреждений, сколько починили?</blockquote>

'''Цепочка вызовов:'''
# <code>get_projects()</code>
# <code>get_snapshots()</code> — два последних
# <code>get_diff(base_snapshot_id="72b3df7b-...", head_snapshot_id="b42cb563-...", level=0)</code>

'''Ответ модели:'''
<blockquote>Между двумя последними снимками paho.mqtt.c:

* Новых: 12
* Удалённых: 13
* Изменённых: 99
* Совпадающих: 185

Удалено несколько больше, чем добавлено — общая картина практически не изменилась.</blockquote>

Категория <code>modified</code> — маркер, присутствующий в обоих снимках, у которого изменилось окружение (номер строки, контекст функции). Это не новая ошибка. На больших проектах рекомендуется начинать с <code>level=0</code> для получения статистики, при необходимости использовать <code>level=1</code> (только идентификаторы маркеров) и затем точечно вызывать <code>get_markers</code> с нужными фильтрами.

<code>level=2</code> возвращает полные маркеры по категориям, причём каждая категория по умолчанию ограничена 20 маркерами. Категории располагаются внутри <code>markers</code>: <code>new_markers</code>, <code>missing_markers</code>, <code>modified_markers</code>, <code>matched_markers</code>. Структура ответа в JSON: <code><nowiki>{"markers": {"new_markers": {"total_count": N, "returned_count": ..., "truncated": ..., "markers": [...]}, ...}}</nowiki></code>. Если требуется полное содержимое категории, следует увеличить <code>limit</code> или выполнить отдельный вызов <code>get_markers</code> по нужным идентификаторам.

=== Разобрать конкретное предупреждение ===
<blockquote>В bash есть один подтверждённый критикал — что-то про разыменование указателя. Покажи код вокруг этого места и объясни в чём проблема.</blockquote>

'''Цепочка вызовов:'''
# <code>get_projects()</code> → <code>get_snapshots()</code> — найти снимок bash
# <code>get_markers(severity=["Critical"], review=["Confirmed"])</code>
# <code>get_advanced_file_preview(file_path="/.build/execute_cmd.c", line=3327, before=10, after=10)</code>

'''Ответ модели:'''
<blockquote>Маркер <code>DEREF_AFTER_NULL.LOOP</code> в функции <code>select_query()</code>, строка 3327:
<code>for (l = list; l && --reply; l = l->next)

;

return (l->word->word); /* l может быть NULL после выхода из цикла */</code>

Если список заканчивается раньше, чем <code>reply</code> обнуляется, <code>l</code> станет <code>NULL</code> на последнем <code>l->next</code>, и следующий <code>l->word->word</code> — разыменование нулевого указателя.</blockquote><code>file_path</code> должен точно совпадать со значением, возвращённым маркером, включая ведущий префикс <code>/.build/...</code>. Это путь внутри сборочной директории Svacer, а не путь в исходном репозитории; соответствие в репозитории определяется по имени файла.

Для одиночной разметки удобно сразу запрашивать полный маркер с трассами: <code>get_markers(..., severity=["Critical"], review=["Confirmed"], traces=True, checker_info=True)</code>. Флаги <code>traces</code> и <code>checker_info</code> указывают серверу включить соответствующие поля в ответ; в выдаче они сохраняются и при значении <code>fields</code> по умолчанию. Значение <code>fields=["*"]</code> требуется лишь в том случае, когда дополнительно нужны <code>tool</code> и <code>mtid</code> — служебные ключи, исключённые из компактного набора.

Help:13-alpha MCP

2026-05-26T10:29:45Z

Vaclovas:

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

[[File:Архитектура MCP.png|thumb|none|x800px|alt=architectureMCP|Архитектура MCP-сервера]]

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

== Установка ==

Svacer MCP может быть подключён к любому серверу Svacer версии 12 и выше. В данном разделе описывается установка Svacer MCP, подключение клиентов и конфигурация.

<code>git clone <nowiki>https://gitlab.ispras.ru/vaclovas/svacermcp.git</nowiki> && cd svacermcp</code>

<code>python3 -m venv .venv</code>

<code>.venv/bin/pip install -e .</code>

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

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

=== Режим STDIO ===
Подходит для настольных клиентов: Claude Desktop, Claude Code, Cursor, VS Code.
cp .env.example .env
# Отредактировать .env — указать URL и учётные данные Svacer

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

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

=== Режим 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: <nowiki>http://localhost:8002/mcp</nowiki>
# Клиенты передают заголовок: Authorization: Bearer <SVACER_MCP_TOKEN>

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

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

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

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

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

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

==== VS Code ====
Файл <code>.vscode/mcp.json</code> в корне рабочей директории:

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

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

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

==== OpenWebUI ====
# Развернуть через Docker (см. [[Help:13-alpha MCP#Режим HTTP (Docker)|Режим HTTP]]).
# Открыть '''Settings → Tools''' (или '''Admin Panel → Settings → Tools''').
# Добавить сервер:
#* <code><nowiki>http://localhost:8002/mcp</nowiki></code> — если OpenWebUI работает на хосте, снаружи Docker.
#* <code><nowiki>http://svacer-mcp:8000/mcp</nowiki></code> — если OpenWebUI развёрнут в той же compose-сети, что и <code>svacer-mcp</code> (имя берётся из <code>docker-compose.yml</code> → service name, порт 8000 — внутренний порт контейнера).
# Тип подключения: '''MCP (Streamable HTTP)'''.
# В настройках инструмента указать заголовок <code>Authorization: Bearer <SVACER_MCP_TOKEN></code> (значение — то же, что в <code>.env</code> сервера).
# Сохранить — инструменты появятся в чате.

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

==== Ограничение набора инструментов ====
Чтобы запустить сервер с подмножеством инструментов (например, для уменьшения объёма контекста у модели или разграничения доступа), задайте <code>SVACER_TOOLS</code>:
SVACER_TOOLS=get_projects,get_snapshots,get_markers
Допустимые имена: <code>get_projects</code>, <code>get_snapshots</code>, <code>get_warnings</code>, <code>get_markers</code>, <code>get_project_stats</code>, <code>get_project_groups</code>, <code>get_advanced_file_preview</code>, <code>get_diff</code>. Неизвестное имя в списке приводит к ошибке при запуске. Если переменная пустая или не задана, регистрируются все 8 инструментов.

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

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

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

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

==== Передача токена клиентом ====
Большинство HTTP-клиентов MCP (OpenWebUI и др.) позволяют задать произвольный заголовок <code>Authorization</code> в настройках инструмента — указывается значение <code>Bearer <токен></code>. Для ручной проверки:
curl -H "Authorization: Bearer $SVACER_MCP_TOKEN" \
<nowiki> </nowiki> -H 'Content-Type: application/json' \
<nowiki> </nowiki> -H 'Accept: application/json, text/event-stream' \
<nowiki> </nowiki> -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' \
<nowiki> </nowiki> <nowiki>http://localhost:8002/mcp</nowiki>

== Инструменты ==
Справочник по 8 инструментам Svacer MCP. Типичный порядок вызовов: <code>get_projects</code> → <code>get_snapshots</code> → любой из аналитических инструментов.
{| class="wikitable"
!Инструмент
!Назначение
|-
|get_projects
|Список проектов с ветками — точка входа
|-
|get_snapshots
|Снимки конкретной ветки, от нового к старому
|-
|get_project_stats
|Агрегированные метрики снимка: severity / review / checker
|-
|get_markers
|Компактный список маркеров с серверной фильтрацией
|-
|get_warnings
|Полные предупреждения с трассами и историей разметки
|-
|get_diff
|Сравнение двух снимков: new / missing / modified / matched
|-
|get_advanced_file_preview
|Фрагмент исходного кода вокруг строки
|-
|get_project_groups
|Группа проектов по имени или UUID
|}

=== get_projects ===
Список всех проектов с ветками. Точка входа: с этого вызова начинается практически любой сценарий — он возвращает <code>project_id</code> и <code>branch_id</code>, необходимые для последующих запросов.

'''Параметров нет.'''

'''Вызов:'''
get_projects()

'''Ответ:'''
[
{
"project_id": "91630e84-db2f-4d8c-8716-68b7fdf17a66",
"project_name": "bash",
"created": "2021-12-13T13:22:42.122456Z",
"created_by": "admin",
"branches": [
{
"branch_id": "77f66b9e-0453-4ae9-a187-88950b4c4bc4",
"branch_name": "master",
"created": "2021-12-13T13:22:42.394812Z"
}
]
}
]
----

=== get_snapshots ===
Список снимков для конкретной ветки проекта, от нового к старому.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|project_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|branch_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|name_filter
|string
|нет
|Подстрока или regex для фильтра по имени снимка
|}

'''Вызов:'''
get_snapshots(
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4"
)

'''Ответ:'''
[
{
"snapshot_id": "b42cb563-86f4-4f96-900a-7782163327c9",
"name": "Snapshot 2020-03-25 09:09:41 +0300",
"import_time": "2020-03-25T09:09:41.837296Z",
"commit_hash": null,
"markers_count": 297,
"link": "<nowiki>https://svacer-demo.ispras.ru/</nowiki>..."
}
]
----

=== get_project_stats ===
Агрегированные метрики по снимку: общее количество предупреждений, распределение по критичности, по статусу разметки, по детекторам. Наиболее быстрый способ получить общую картину по проекту.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|project_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|branch_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|snapshot_id
|string (UUID)
|да
|Из <code>get_snapshots</code>
|}

'''Вызов:'''
get_project_stats(
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4",
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9"
)

'''Ответ:'''
{
"total_warnings": 771,
"by_severity": {
"Critical": 1,
"Major": 1,
"Unspecified": 769
},
"by_review_status": {
"Confirmed": 1,
"False Positive": 1,
"Undecided": 767,
"Unclear": 1,
"Won't fix": 1
},
"by_checker": {
"PROC_USE.VULNERABLE": 337,
"UNUSED_FUNC_RES.REWRITE.MINOR": 44,
"UNREACHABLE_CODE": 28,
"DEREF_AFTER_NULL.EX": 27,
"NULL_AFTER_DEREF": 27
}
}
----

=== get_markers ===
Компактный список маркеров с серверной фильтрацией. Основной инструмент для перечисления и обзора: его следует предпочитать <code>get_warnings</code>, когда не требуются развёрнутые поля — трассы и история разметки.

По умолчанию ответ ограничен 30 маркерами и содержит компактный набор полей. Подробнее об ограничении объёма см. раздел [[Help:13-alpha MCP#Про объём ответа|Про объём ответа]].

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|project_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|branch_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|snapshot_id
|string (UUID)
|да
|Из <code>get_snapshots</code>
|-
|severity
|string[]
|нет
|<code>Critical</code>, <code>Major</code>, <code>Minor</code>, <code>Unspecified</code>. Фильтр по <code>review.severity</code> применяется на стороне коннектора
|-
|review
|string[]
|нет
|<code>Confirmed</code>, <code>Won't fix</code>, <code>False Positive</code>, <code>Unclear</code>
|-
|warnClass
|string[]
|нет
|Идентификатор детектора (<code>DEREF_AFTER_NULL</code>, …)
|-
|file
|string[]
|нет
|Подстрока пути к файлу
|-
|traces
|bool
|нет
|Включить трассы маркеров
|-
|checker_info
|bool
|нет
|Включить метаданные детектора (CWE, описание)
|-
|review_history
|bool
|нет
|Включить историю изменений разметки
|-
|comment_history
|bool
|нет
|Включить комментарии к маркеру
|-
|custom_filter
|string
|нет
|Имя или идентификатор сохранённого фильтра из веб-интерфейса Svacer
|-
|limit
|int
|нет
|Максимальное количество маркеров в ответе (по умолчанию 30). Значение 0 снимает ограничение
|-
|fields
|string[]
|нет
|Список разрешённых полей маркера верхнего уровня. По умолчанию — компактный набор <code>id, warnClass, file, line, msg, function, review</code>. Значение <code>["*"]</code> возвращает все поля коннектора (<code>id, warnClass, file, line, msg, tool, function, mtid, review</code>, а также <code>traces</code>/<code>checkerInfo</code>/<code>review_history</code>/<code>comments</code>, если они запрошены). Допустим и произвольный список, например <code>["id","warnClass"]</code>
|}

'''Вызов:'''
get_markers(
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4",
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",
warnClass=["PROC_USE.VULNERABLE"]
)

'''Ответ:'''
{
"total_count": 341,
"returned_count": 30,
"truncated": true,
"filters_applied": {"warnClass": ["PROC_USE.VULNERABLE"]},
"markers": [
{
"id": "e05bb35b-a95e-4eb2-85ae-3101b788f07d",
"warnClass": "PROC_USE.VULNERABLE.TEMP",
"file": "/.build/lib/sh/tmpfile.c",
"line": 160,
"msg": "Use of vulnerable function 'mktemp' at tmpfile.c:160. ...",
"function": "sh_mktmpname",
"review": null
}
]
}

<code>total_count</code> отражает количество маркеров, удовлетворяющих фильтру до применения ограничения; <code>returned_count</code> — количество маркеров, фактически содержащихся в <code>markers</code>. При <code>truncated: true</code> следует либо сузить фильтры (<code>severity</code>, <code>warnClass</code>, <code>file</code>), либо передать <code>limit=0</code> для получения полного списка. Поля <code>tool</code> и <code>mtid</code> возвращаются только при <code>fields=["*"]</code>.
----

=== get_warnings ===
Полные предупреждения с детальной разметкой. Ответ значительно объёмнее, чем у <code>get_markers</code>, поэтому инструмент следует использовать только тогда, когда нужны поля, отсутствующие в компактной форме: <code>traces</code>, <code>review_history</code>, <code>checker_info</code>, <code>comment_history</code>.

Лимит по умолчанию — 30; при включённых <code>traces</code>, <code>review_history</code> или <code>comment_history</code> он автоматически снижается до 8, поскольку такие предупреждения существенно объёмнее.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|project_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|branch_id
|string (UUID)
|да
|Из <code>get_projects</code>
|-
|snapshot_id
|string (UUID)
|да
|Из <code>get_snapshots</code>
|-
|severity
|string[]
|нет
|<code>Critical</code>, <code>Major</code>, <code>Minor</code>, <code>Unspecified</code>. Фильтр по <code>review.severity</code>, применяется на стороне коннектора
|-
|review
|string[]
|нет
|<code>Confirmed</code>, <code>Won't fix</code>, <code>False Positive</code>, <code>Unclear</code>
|-
|warnClass
|string[]
|нет
|Идентификатор детектора
|-
|file
|string[]
|нет
|Подстрока пути к файлу
|-
|traces
|bool
|нет
|Включить трассы. Активирует режим расширенных полей (лимит по умолчанию — 8)
|-
|checker_info
|bool
|нет
|Включить метаданные детектора (CWE, описание)
|-
|review_history
|bool
|нет
|Включить историю разметки. Режим расширенных полей
|-
|comment_history
|bool
|нет
|Включить комментарии. Режим расширенных полей
|-
|custom_filter
|string
|нет
|Имя или идентификатор сохранённого фильтра
|-
|limit
|int
|нет
|Максимальное количество предупреждений в ответе. По умолчанию — 30, в режиме расширенных полей — 8. Значение 0 снимает ограничение. Явно заданное <code>limit</code> отменяет автоматическое снижение
|-
|fields
|string[]
|нет
|См. описание в <code>get_markers</code>
|}
'''Вызов:'''
get_warnings(
project_id="91630e84-db2f-4d8c-8716-68b7fdf17a66",
branch_id="77f66b9e-0453-4ae9-a187-88950b4c4bc4",
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",
severity=["Critical"],
review_history=True,
traces=True
)

'''Ответ:'''
{
"total_count": 1,
"returned_count": 1,
"truncated": false,
"filters_applied": {"severity": ["Critical"], "traces": true, "review_history": true},
"warnings": [
{
"id": "a3f21c90-1d4e-4b82-9f63-7c8e5d2a1b09",
"warnClass": "DEREF_AFTER_NULL.LOOP",
"file": "/.build/execute_cmd.c",
"line": 3327,
"msg": "Possible null pointer dereference of 'l' after loop exit.",
"function": "select_query",
"review": {"status": "Confirmed", "severity": "Critical"},
"review_history": [{"status": "Confirmed", "changed_by": "admin", "changed_at": "2021-12-13T14:00:00Z"}],
"traces": [{"file": "/.build/execute_cmd.c", "line": 3320, "msg": "Loop starts here; 'l' may exhaust the list."}]
}
]
}
----

=== get_diff ===
Сравнение двух снимков. Категории располагаются под ключом <code>markers</code>: <code>new_markers</code> (появилось в новом снимке), <code>missing_markers</code> (исчезло из нового), <code>modified_markers</code> (тот же идентификатор, изменился контекст), <code>matched_markers</code> (совпало в обоих). Параметры <code>project_id</code> и <code>branch_id</code> не требуются — достаточно UUID снимков.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|base_snapshot_id
|string (UUID)
|да
|Старый снимок
|-
|head_snapshot_id
|string (UUID)
|нет
|Новый снимок; если не указан, сравнение выполняется с предыдущим по времени
|-
|level
|int
|нет
|0 — только статистика; 1 — статистика и идентификаторы маркеров; 2 — полные маркеры по категориям
|-
|checker_info
|bool
|нет
|Метаданные детекторов для маркеров (только при <code>level >= 2</code>)
|-
|limit
|int
|нет
|Максимальное количество маркеров '''на каждую категорию''' при <code>level >= 2</code>. По умолчанию — 20, значение 0 снимает ограничение. Параметр игнорируется при <code>level < 2</code>
|-
|fields
|string[]
|нет
|См. описание в <code>get_markers</code>. Применяется к маркерам внутри категорий при <code>level >= 2</code>
|}

'''Вызов (<code>level=0</code>):'''
get_diff(
base_snapshot_id="72b3df7b-c15a-4e3d-8f92-a041dc6e5b87",
head_snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",
level=0
)

'''Ответ (<code>level=0</code>):'''
{
"stats": {
"context1": {"projectName": "paho.mqtt.c", "snapshotName": "Snapshot 2020-03-20 ..."},
"context2": {"projectName": "paho.mqtt.c", "snapshotName": "Snapshot 2020-03-25 ..."},
"scope": ["NEW", "MISSING", "MATCHED", "MODIFIED"],
"new": 9,
"missing": 12,
"modified": 98,
"matched": 187
}
}

'''Ответ (<code>level=2</code>)''' — каждая категория внутри <code>markers</code> оформляется и ограничивается независимо:
{
"stats": {"new": 50, "missing": 5, "modified": 0, "matched": 187},
"markers": {
"new_markers": {
"total_count": 50,
"returned_count": 20,
"truncated": true,
"markers": [
{"id": "a3f21c90-...", "warnClass": "DEREF_AFTER_NULL.LOOP", "file": "...", "line": 3327, "msg": "...", "function": "select_query", "review": null}
]
},
"missing_markers": {"total_count": 5, "returned_count": 5, "truncated": false, "markers": [...]},
"modified_markers": {"total_count": 0, "returned_count": 0, "truncated": false, "markers": []},
"matched_markers": {"total_count": 187, "returned_count": 20, "truncated": true, "markers": [...]}
}
}

Если требуется полное содержимое категории, следует увеличить <code>limit</code>, либо запросить нужные идентификаторы отдельным вызовом <code>get_markers</code>. Маркеры внутри категорий проходят ту же компактную обработку, что и в <code>get_warnings</code>: значение <code>fields=["*"]</code> возвращает фиксированный набор полей коннектора, а не произвольные «сырые» поля API.
----

=== get_advanced_file_preview ===
Фрагмент исходного кода из снимка вокруг указанной строки. Параметры <code>project_id</code> и <code>branch_id</code> не требуются — достаточно идентификатора снимка и пути к файлу.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|snapshot_id
|string (UUID)
|да
|UUID снимка
|-
|file_path
|string
|да
|Путь к файлу в том виде, в котором его возвращают <code>get_markers</code> и <code>get_warnings</code>
|-
|line
|int
|нет
|Центральная строка, нумерация с 1 (по умолчанию 1)
|-
|before
|int
|нет
|Количество строк до центральной (по умолчанию 0)
|-
|after
|int
|нет
|Количество строк после центральной (по умолчанию 99999 — до конца файла)
|}

'''Вызов:'''
get_advanced_file_preview(
snapshot_id="b42cb563-86f4-4f96-900a-7782163327c9",
file_path="/.build/execute_cmd.c",
line=3327,
before=10,
after=10
)

'''Ответ:'''
{
"line": 3327,
"content": " for (l = list; l && --reply; l = l->next)\n\t;\n return (l->word->word);\n",
"total_lines": 6082
}
----

=== get_project_groups ===
Получить группу проектов по имени или UUID. Группы объединяют проекты в логические блоки — например, по команде или продукту.

'''Параметры.'''
{| class="wikitable"
!Имя
!Тип
!Обязательный
!Описание
|-
|name_or_id
|string
|да
|Имя группы или её UUID
|}

'''Вызов:'''
get_project_groups(name_or_id="Linux Tools")

'''Ответ:'''
{
"project_group_id": "c4f8a2d1-3b7e-4f90-82ac-1d5e8f2b6c04",
"project_group_name": "Linux Tools",
"projects": [
{"id": "91630e84-db2f-4d8c-8716-68b7fdf17a66", "name": "bash"},
{"id": "d3a17f52-...", "name": "coreutils"}
]
}

<code>projects[].id</code> — это <code>project_id</code>, который далее передаётся в <code>get_snapshots</code>. Группы и проекты — разные сущности; идентификатор группы и идентификатор проекта не взаимозаменяемы.

== Примеры сценариев ==
Приведённые ниже запросы выполнены на демонстрационном стенде <code>svacer-demo.ispras.ru</code> с использованием OpenWebUI и модели <code>qwen3-coder:30b</code>. В любом другом MCP-клиенте с моделью достаточной мощности порядок вызовов будет аналогичным.

=== Про объём ответа ===
<code>get_markers</code>, <code>get_warnings</code> и <code>get_diff(level=2)</code> по умолчанию ограничивают объём ответа, чтобы не перегружать контекст модели:

* <code>get_markers</code> и <code>get_warnings</code> — 30 маркеров по умолчанию. Если у <code>get_warnings</code> включены <code>traces</code>, <code>review_history</code> или <code>comment_history</code>, лимит снижается до 8, поскольку такие маркеры значительно объёмнее.
* <code>get_diff(level=2)</code> — 20 маркеров на каждую категорию внутри <code>markers</code> (<code>new_markers</code>/<code>missing_markers</code>/<code>modified_markers</code>/<code>matched_markers</code>).

В ответе присутствуют поля <code>total_count</code>, <code>returned_count</code>, <code>truncated</code>. При <code>truncated: true</code> есть два варианта действий: сузить фильтр (<code>severity</code>, <code>warnClass</code>, <code>file</code>) либо явно увеличить <code>limit</code> (значение <code>limit=0</code> полностью снимает ограничение).

Поле <code>fields</code> определяет, какие ключи маркера возвращаются. По умолчанию применяется компактный набор <code>id, warnClass, file, line, msg, function, review</code> (а также <code>traces</code>/<code>checkerInfo</code>/<code>review_history</code>/<code>comments</code>, если они запрошены логическими флагами и пришли с сервера). Для полного маркера со всеми служебными ключами — <code>fields=["*"]</code>. Для произвольной выборки — список полей верхнего уровня, например <code>fields=["id","warnClass"]</code>. Поле <code>review</code> — объект <code>{status, severity, action}</code>; вложенные ключи в <code>fields</code> не поддерживаются, поэтому объект <code>review</code> запрашивается целиком.

=== Перечислить все проекты ===
<blockquote>Какие проекты есть в Svacer?</blockquote>

'''Цепочка вызовов:'''
# <code>get_projects()</code>

'''Ответ модели:'''
<blockquote>В Svacer доступно 6 проектов: bash, openssl, paho.mqtt.c, coturn, zstd, darpa. У каждого — одна ветка <code>master</code>.</blockquote>

=== Посмотреть снимки проекта ===
<blockquote>Какие снимки есть у paho.mqtt.c? Самый свежий когда?</blockquote>'''Цепочка вызовов:'''

# <code>get_projects()</code> — найти <code>project_id</code> и <code>branch_id</code>
# <code>get_snapshots(project_id=..., branch_id=...)</code>

'''Ответ модели:'''
<blockquote>У paho.mqtt.c 3 снимка. Самый свежий — «Snapshot 2020-03-25 09:09:41 +0300» (297 маркеров). Предыдущий — 20 марта (306 маркеров).</blockquote>Поле <code>commit_hash</code> может принимать значение <code>null</code>, если проект не сохраняет хэш коммита в <code>custom_properties</code>. Имена снимков произвольны: одни проекты записывают в имя дату, другие — коммит, третьи — свободный текст.

=== Сводка по проекту ===
<blockquote>Что в bash в последнем снимке? Сколько всего предупреждений, есть ли критические, какие топ-детекторы?</blockquote>

'''Цепочка вызовов:'''
# <code>get_projects()</code>
# <code>get_snapshots(project_id, branch_id)</code> — взять последний снимок
# <code>get_project_stats(project_id, branch_id, snapshot_id)</code>

'''Ответ модели:'''
<blockquote>В последнем снимке bash содержится 771 предупреждение:

* Критических: 1 (Confirmed)
* Major: 1 (Won't fix)
* Остальные: 769 (Unspecified — не размечались)

Топ-детекторы по количеству:

# <code>PROC_USE.VULNERABLE</code> — 337
# <code>UNUSED_FUNC_RES.REWRITE.MINOR</code> — 44
# <code>UNREACHABLE_CODE</code> — 28
# <code>DEREF_AFTER_NULL.EX</code> — 27
# <code>NULL_AFTER_DEREF</code> — 27
</blockquote>

<code>Unspecified</code> в <code>by_severity</code> — маркеры без ручной разметки, а не «низкий приоритет». Поле <code>by_checker</code> не сортируется, на большом снимке оно может содержать более 100 ключей — чтобы получить именно топ-N, следует явно сформулировать запрос: «топ-5 детекторов».

=== Тренд по нескольким снимкам ===
<blockquote>Как у openssl менялось число предупреждений за последние пять снимков? Покажи таблицей.</blockquote>

'''Цепочка вызовов:'''

# <code>get_projects()</code>
# <code>get_snapshots()</code> — взять список
# <code>get_project_stats()</code> × 5 — по каждому из последних пяти снимков

'''Ответ модели:'''
<blockquote>
{| class="wikitable"
|+
!Снимок
!Дата
!Всего
|-
|2020-04-30 05:49
|30.04.2020
|1252
|-
|2020-04-30 05:29
|30.04.2020
|1252
|-
|2020-04-30 05:08
|30.04.2020
|1252
|-
|2020-04-30 04:48
|30.04.2020
|1252
|-
|2020-04-30 04:22
|30.04.2020
|1252
|}
</blockquote>

На демонстрационном стенде указанные пять снимков openssl импортированы с интервалом в 20 минут одного дня и полностью идентичны — поэтому динамика отсутствует. На реальном проекте с историей релизов значения будут изменяться.

=== Найти срабатывания конкретного детектора ===
<blockquote>Где в bash срабатывает PROC_USE.VULNERABLE? Покажи список — файл, строка, что именно ругается. Достаточно первых десяти.</blockquote>

'''Цепочка вызовов:'''
# <code>get_projects()</code>
# <code>get_snapshots()</code>
# <code>get_markers(warnClass=["PROC_USE.VULNERABLE"])</code>

'''Ответ модели:'''
<blockquote>
# <code>/.build/lib/sh/tmpfile.c:160</code> — <code>mktemp()</code>, race condition. Рекомендуется <code>mkstemp()</code>.
# <code>/.build/lib/readline/shell.c:151</code> — <code>getenv()</code>, значение может быть подменено.
# <code>/.build/shell.c:415</code> — <code>getenv()</code> в <code>main()</code>.
# <code>/.build/lib/readline/complete.c:1516</code> — <code>getenv()</code>.
# <code>/.build/lib/sh/eaccess.c:115</code> — <code>strcat()</code>, рекомендуется <code>strncat()</code>.
</blockquote>

Фильтр <code>warnClass=["PROC_USE.VULNERABLE"]</code> охватывает все подклассы: <code>PROC_USE.VULNERABLE.TEMP</code>, <code>.GETENV</code>, <code>.STRCAT</code> и т. д. — всего 341 маркер. Несколько значений в одном параметре трактуются как логическое «ИЛИ»: <code>severity=["Critical","Major"]</code> возвращает маркеры обеих категорий.

В ответе будет <code>total_count: 341, returned_count: 30, truncated: true</code> — это ожидаемое поведение. Модель видит общий объём по <code>total_count</code> и при необходимости сужает запрос или вызывает <code>get_markers(..., limit=0)</code>, чтобы получить полный список.

=== Сравнить два снимка ===
<blockquote>Возьми два последних снимка paho.mqtt.c — что между ними изменилось? Сколько новых предупреждений, сколько починили?</blockquote>

'''Цепочка вызовов:'''
# <code>get_projects()</code>
# <code>get_snapshots()</code> — два последних
# <code>get_diff(base_snapshot_id="72b3df7b-...", head_snapshot_id="b42cb563-...", level=0)</code>

'''Ответ модели:'''
<blockquote>Между двумя последними снимками paho.mqtt.c:

* Новых: 12
* Удалённых: 13
* Изменённых: 99
* Совпадающих: 185

Удалено несколько больше, чем добавлено — общая картина практически не изменилась.</blockquote>

Категория <code>modified</code> — маркер, присутствующий в обоих снимках, у которого изменилось окружение (номер строки, контекст функции). Это не новая ошибка. На больших проектах рекомендуется начинать с <code>level=0</code> для получения статистики, при необходимости использовать <code>level=1</code> (только идентификаторы маркеров) и затем точечно вызывать <code>get_markers</code> с нужными фильтрами.

<code>level=2</code> возвращает полные маркеры по категориям, причём каждая категория по умолчанию ограничена 20 маркерами. Категории располагаются внутри <code>markers</code>: <code>new_markers</code>, <code>missing_markers</code>, <code>modified_markers</code>, <code>matched_markers</code>. Структура ответа в JSON: <code><nowiki>{"markers": {"new_markers": {"total_count": N, "returned_count": ..., "truncated": ..., "markers": [...]}, ...}}</nowiki></code>. Если требуется полное содержимое категории, следует увеличить <code>limit</code> или выполнить отдельный вызов <code>get_markers</code> по нужным идентификаторам.

=== Разобрать конкретное предупреждение ===
<blockquote>В bash есть один подтверждённый критикал — что-то про разыменование указателя. Покажи код вокруг этого места и объясни в чём проблема.</blockquote>

'''Цепочка вызовов:'''
# <code>get_projects()</code> → <code>get_snapshots()</code> — найти снимок bash
# <code>get_markers(severity=["Critical"], review=["Confirmed"])</code>
# <code>get_advanced_file_preview(file_path="/.build/execute_cmd.c", line=3327, before=10, after=10)</code>

'''Ответ модели:'''
<blockquote>Маркер <code>DEREF_AFTER_NULL.LOOP</code> в функции <code>select_query()</code>, строка 3327:
<code>for (l = list; l && --reply; l = l->next)

;

return (l->word->word); /* l может быть NULL после выхода из цикла */</code>

Если список заканчивается раньше, чем <code>reply</code> обнуляется, <code>l</code> станет <code>NULL</code> на последнем <code>l->next</code>, и следующий <code>l->word->word</code> — разыменование нулевого указателя.</blockquote><code>file_path</code> должен точно совпадать со значением, возвращённым маркером, включая ведущий префикс <code>/.build/...</code>. Это путь внутри сборочной директории Svacer, а не путь в исходном репозитории; соответствие в репозитории определяется по имени файла.

Для одиночной разметки удобно сразу запрашивать полный маркер с трассами: <code>get_markers(..., severity=["Critical"], review=["Confirmed"], traces=True, checker_info=True)</code>. Флаги <code>traces</code> и <code>checker_info</code> указывают серверу включить соответствующие поля в ответ; в выдаче они сохраняются и при значении <code>fields</code> по умолчанию. Значение <code>fields=["*"]</code> требуется лишь в том случае, когда дополнительно нужны <code>tool</code> и <code>mtid</code> — служебные ключи, исключённые из компактного набора.