bsl-ls-mcp

MCP-обёртка над BSL Language Server для статического анализа и навигации по коду 1С (BSL). Один интерфейс наружу — инструменты mcp__bsl-ls__* для агентов и любых MCP-клиентов.

Статус проекта. Инструмент рабочий и используется в бою, но развивается по остаточному принципу: делюсь как есть. Активной поддержки, разбора issue и приёма правок в срок не обещаю — реагирую по возможности и без гарантий. Форки и адаптация под свои задачи только приветствуются.

Подробности (архитектура, сборка, все настройки, внутренняя механика) — в README_full.md. Здесь — только как запустить и что умеет.

Что нужно

• Рабочая копия исходников 1С в формате CR-выгрузки (каталог src/cf).

• ~14 ГБ свободной RAM — для навигации (граф держится в памяти). Диагностикам индекс не нужен, им хватает ~2 ГБ на разовый вызов.

• Java 17+ или готовый бандл с portable JRE (Python/Java ставить не надо).

Related MCP server: bsl-context

Запуск

Вариант 1. Готовый бандл (рекомендуется)

Папка dist\bsl-ls-mcp\ самодостаточна (внутри Python и Java). На целевой машине:

:: 1. указать путь к исходникам 1С (или отредактировать BSL_WORKSPACE в run.cmd)
set BSL_WORKSPACE=C:\1c\src\cf

:: 2. проверка — должно напечатать [selftest] OK
run.cmd --selftest

:: 3. запуск демона (streamable-http на :8081/mcp)
run.cmd

Как Windows-служба (автозапуск, авто-рестарт) — из-под администратора:

powershell -ExecutionPolicy Bypass -File install-service.ps1 -Workspace "C:\1c\src\cf"

Удобный пультик к службе (лампочка статуса + старт/стоп/переиндекс) — bsl-ls-tray.exe.

Вариант 2. С исходников (нужны Python 3.10+ и Java 17+)

py -3 -m pip install -e .
$env:BSL_WORKSPACE = "C:\1c\src\cf"
bsl-ls-mcp --transport streamable-http --port 8081     # → http://127.0.0.1:8081/mcp

Подключение к MCP-клиенту

В .mcp.json клиента (агентского пайплайна):

{ "bsl-ls": { "type": "streamable-http", "url": "http://127.0.0.1:8081/mcp" } }

Первый вызов навигации подождёт индекс (~1.5 мин), дальше — мгновенно. Диагностики доступны сразу.

Безопасность. Демон не аутентифицирует вызовы и по умолчанию слушает только 127.0.0.1. Не выставляйте порт в сеть без обратного прокси с авторизацией (BSL_MCP_HOST=0.0.0.0 заблокирован без BSL_ALLOW_REMOTE=1). path-режим ограничен BSL_WORKSPACE и BSL_ALLOWED_ROOTS. Подробнее — SECURITY.md.

Как устроено имя объекта

Везде, где инструмент просит имя — это строка с точками, как в ПолноеИмя() 1С:

Тип.Модуль                  → операции над модулем (диагностики)
Тип.Модуль.Метод            → навигация по функции/процедуре
Тип.Объект.Форма.ИмяФормы   → модуль формы (для диагностик)

Примеры: ОбщийМодуль.ОбщегоНазначения, Справочник.Контрагенты.Форма.ФормаЭлемента, ОбщийМодуль.ОбщегоНазначения.ЗначениеРеквизитаОбъекта.

Код вне корпуса (внешние обработки/отчёты) адресуется не именем, а параметром path — произвольный каталог или .bsl-файл; индексированный корпус для этого не нужен (см. bsl_diagnostics ниже).

Методы

Что возвращают (коротко)

• bsl_diagnostics → {diagnostics, suppressed}. По умолчанию diagnostics — полный список только error+warning (error первыми); стилевой шум info/hint свёрнут в suppressed.by_code (счётчики по кодам, чтобы не раздувать ответ). Детали свёрнутого — вызов с code="Typo". Поле file точно указывает модуль (менеджер/объект/форма), а для кода вне корпуса — путь файла относительно переданного path. Адрес — ровно один из двух:

  bsl_diagnostics(module_full_name="ОбщийМодуль.МойМодуль")        # модуль корпуса
  bsl_diagnostics(path=r"C:\1c\work\<задача>\Реализация")          # внешняя обработка
  bsl_diagnostics(path=r"...\Ext\ObjectModule.bsl")                # один файл

• bsl_callers / bsl_callees → список {name, type, full_name, kind} — full_name можно сразу подать в другой инструмент.

• bsl_definition / bsl_references → список {type, module, full_name, line, text} — line 1-based, text — сама строка кода.

• bsl_complexity → список {full_name, cognitive, cyclomatic}.

Имена в ответах — русские (как у 1С).

Поведение

• Первый вызов навигации после старта ждёт индексацию (~1.5 мин на боевом корпусе), дальше — доли секунды. Диагностики индекс не ждут — отрабатывают всегда за ~5–8 c.

• Свежесть: правки на диске видны без перезапуска (навигация — по didChange, диагностики читают файл заново).

• Имя не разрешилось → понятная ошибка; нет результатов → пустой список.

Полная документация по параметрам, переменным окружения и устройству — в README_full.md.