MCP для ИИ-инструментов¶

MCP (Model Context Protocol) — протокол, через который среда разработки или ИИ-агент получает доступ к внешним инструментам и источникам данных.

Для v8std.ru MCP-сервер дает агенту структурированный доступ к стандартам, диагностикам и связям между ними. Вместо того чтобы искать страницы через браузер, агент вызывает методы MCP: ищет стандарт, получает страницу по идентификатору, переходит к связанным диагностикам или объясняет предупреждение анализатора.

Основной сценарий — совместная работа с локальными инструментами анализа кода, например с bsl-analyzer или BSL Language Server:

1. локальный анализатор проверяет исходный код проекта и находит диагностику;
2. агент запрашивает в MCP описание диагностики и связанные стандарты;
3. агент предлагает исправление с учетом причины нарушения, а не только текста предупреждения.

MCP-сервер v8std не анализирует исходный код пользователя и не принимает файлы конфигурации. Он работает как read-only банк знаний по публичным материалам сайта.

Подключение готового сервиса¶

Публичный MCP-сервер доступен по адресу:

https://ai.v8std.ru/mcp

Подключение к Codex:

codex mcp add v8std --url https://ai.v8std.ru/mcp

Подключение к Claude Code:

claude mcp add --transport http v8std https://ai.v8std.ru/mcp

Проверочные endpoint'ы:

https://ai.v8std.ru/healthz
https://ai.v8std.ru/version

Готовый сервис использует опубликованный индекс сайта и подходит для обычной работы в IDE: поиск стандартов, объяснение диагностики, подбор связанных страниц.

Локальный запуск¶

Локальный вариант нужен, если требуется полностью автономный запуск по файлам репозитория или нужно проверить изменения сайта до публикации.

git clone https://github.com/zeegin/v8std.git
cd v8std

docker compose -f docker-compose/docker-compose.yml up -d v8std-mcp

MCP будет доступен локально:

http://127.0.0.1:8765/mcp

Подключение к Codex:

codex mcp add v8std-local --url http://127.0.0.1:8765/mcp

Подключение к Claude Code:

claude mcp add --transport http v8std-local http://127.0.0.1:8765/mcp

Локальный контейнер монтирует репозиторий в /docs и читает файлы /docs/docs/ai/pages.jsonl и /docs/docs/ai/search-vectors.jsonl. При V8STD_MCP_GENERATE_INDEX=auto индекс и векторы генерируются при старте контейнера, если файлы отсутствуют.

Полезные команды:

curl http://127.0.0.1:8765/healthz
docker logs v8std-mcp
docker compose -f docker-compose/docker-compose.yml restart v8std-mcp

Инструменты MCP¶

v8std.search¶

Ищет страницы гибридным ранжированием: точные алиасы и коды диагностик, BM25 по заголовкам и тексту, статический векторный индекс и доменные правила.

Подходит для сценариев:

• найти стандарт по std437, #std437, стандарт 437;
• найти диагностику по acc:1245, апк 1245, AssignAliasFieldsInQuery;
• найти материалы по теме: запросы, регламентные задания, права;
• найти смысловой запрос: форма не должна содержать бизнес-логику и доступ к данным;
• разобрать кодовый фрагмент: Новый Запрос("ВЫБРАТЬ РАЗРЕШЕННЫЕ ...").

Основные параметры:

v8std.page¶

Возвращает страницу по идентификатору, алиасу, пути или URL.

Подходит для сценариев:

• получить полный текст стандарта перед исправлением кода;
• открыть Markdown-версию страницы по HTML-ссылке;
• получить описание диагностики по точному коду.

Основные параметры:

v8std.related¶

Возвращает связанные стандарты, диагностики и проверки EDT.

Подходит для сценариев:

• от стандарта перейти к диагностике анализатора;
• от диагностики перейти к стандарту, объясняющему причину;
• собрать контекст для code review или автоисправления.

Основные параметры:

v8std.explain_snippet¶

Разбирает короткий фрагмент BSL/SDBL и возвращает распознанные токены, сигналы, вероятные диагностики, стандарты и confidence.

Подходит для сценариев:

• передать Запрос = Новый Запрос("ВЫБРАТЬ РАЗРЕШЕННЫЕ ...") и получить std415;
• передать ОткрытьФормуМодально, Предупреждение, Вопрос и получить bslls:UsingModalWindows;
• отделить кодовые токены от обычного текстового поиска.

Основные параметры:

v8std.explain_diagnostics¶

Объясняет список диагностик и группирует связанные стандарты.

Подходит для сценариев:

• после запуска bsl-analyzer объяснить пачку предупреждений;
• сгруппировать отчет BSL Language Server по стандартам;
• выбрать исправления, которые устраняют причины нарушений.

Основные параметры:

Файлы для ИИ-инструментов¶

Сайт генерирует несколько статических файлов, которые можно использовать без MCP.

/ai/pages.jsonl является основным источником данных для MCP. Каждая строка — отдельная страница со следующими полями:

/ai/search-vectors.jsonl строится из pages.jsonl. MCP читает этот файл как готовый read-only индекс; если файл временно недоступен, сервер продолжает работать через точные правила и BM25, а /healthz показывает semantic_enabled: false.

Через MCP resources доступны:

v8std://llms.txt
v8std://llms-full.txt
v8std://ai/pages.jsonl

Страницы с front matter llms.ignore: true исключаются из /llms.txt, /llms-full.txt и /ai/pages.jsonl, но остаются обычными страницами сайта.

Детали для разработчиков¶

Код локального MCP находится в репозитории:

Переменные локального Docker-запуска:

Локальная проверка MCP без Docker:

python3.12 -m venv .venv
source .venv/bin/activate

pip install -r requirements.txt -r requirements-mcp.txt
python scripts/generate_ai_artifacts.py
python scripts/generate_search_vectors.py
python scripts/v8std_mcp_server.py \
  --pages docs/ai/pages.jsonl \
  --vectors docs/ai/search-vectors.jsonl \
  --host 127.0.0.1 \
  --port 8765

Проверка качества поиска:

python -m unittest tests.test_v8std_mcp_index
python scripts/search_benchmark.py

MCP-сервер intentionally read-only: он не изменяет код пользователя, не запускает анализаторы и не принимает исходники. Для анализа проекта подключайте локальный bsl-analyzer или другой анализатор отдельным инструментом, а v8std используйте как источник стандартов, связей и объяснений.