bsl-ctx

Точная справка по платформе 1С:Предприятие для агента-разработчика.

bsl-ctx собирает из файлов справки .hbk установленной платформы 1С базу данных о типах, методах, свойствах, событиях, перегрузках, параметрах и доступности по средам — и отдаёт её агенту через MCP-сервер. Без запуска самой 1С.

Что это и чего не делает

Делает: поиск по естественным формулировкам («хеш SHA256 от файла»), карточки сущностей с сигнатурами и примерами, списки членов типа, связи типов (что возвращает / чем расширяется), самоориентацию агента (версия платформы, схема). Шесть инструментов MCP, CLI с теми же командами, и Markdown-, и JSON-ответ.

Не делает: не запускает 1С, не выполняет код, не подключается к информационной базе. Справка читается один раз из .hbk при сборке БД; агент работает с готовым read-only файлом.

Установка и сборка

Нужен uv и установленная платформа 1С:Предприятие (из неё читается справка .hbk). Пакет ставится из PyPI, клонировать репозиторий не нужно: сборка БД и подключение к агенту — одна команда.

1. Собрать БД одной командой

uvx bsl-ctx setup

bsl-ctx setup — единственная команда установки: находит установленную платформу 1С, собирает из её справки корпус и БД продукта, (опционально) обогащает данными «Инструментов разработчика» и печатает готовую команду подключения MCP. Артефакты ложатся в каталог данных — ~/.local/share/bsl-ctx/ на Linux (~/Library/Application Support/bsl-ctx на macOS, %LOCALAPPDATA%\bsl-ctx на Windows), не в рабочий проект и не в репозиторий.

uvx bsl-ctx setup --no-ir                  # без обогащения ИР
uvx bsl-ctx setup --platform 8.3.27.1688   # версий несколько
uvx bsl-ctx setup --rebuild                # пересобрать

Шаг ИР необязателен и не обрывает сборку: без сети или --no-ir БД всё равно собирается — теряется только обогащение (avail_ir, guid, расширения).

2. Подключить к агенту

setup печатает два варианта — claude mcp add … (Claude Code) и блок .mcp.json (любой клиент). Путь к собранной БД подставляется автоматически, номера версии пакета в команде нет — .mcp.json переживает обновления без правок.

claude mcp add bsl-ctx -- uvx --from bsl-ctx \
    bsl-ctx serve --db ~/.local/share/bsl-ctx/bsl-context-8.3.27.1688.sqlite

Проверить подключение — у агента вызвать platform_info (должен вернуть schema_version: 0.6.0). serve без --db сам найдёт единственную или свежую по версии БД в каталоге данных — абсолютный путь можно убрать.

Обновление

Номер новой версии знать не нужно — @latest ставит последнюю с PyPI:

uvx --from bsl-ctx@latest bsl-ctx setup --rebuild --platform 8.3.27.1688

.mcp.json проектов при этом не трогается: подключение живёт без номера версии, а незакреплённый uvx сам подхватывает новую версию пакета — serve обновится при следующем запуске агента. --rebuild пересобирает БД и при обновлении пакета не обязателен (формат БД стабилен, несовпадение схемы serve встретит внятной ошибкой с командой пересборки); --platform нужен, только если платформ несколько.

Каталог данных и сопровождение

Каталог данных переопределяется переменной BSL_CTX_DATA_DIR или флагом --data-dir.

Несколько проектов 1С

Файл БД — справочник по платформе, а не по конфигурациям: один bsl-context-8.3.27.1688.sqlite подключается к нескольким рабочим проектам (у каждого свой .mcp.json с тем же абсолютным путём), различаясь только целевой версией (BSL_CTX_TARGET_VERSION). Отдельная БД нужна лишь под другую версию платформы — setup соберёт её рядом, list покажет обе.

Ручная сборка (пошагово)

setup оркеструет те же команды; ниже — если нужен контроль каждого шага. Команды запускаются через uvx из пакета в PyPI (в клоне репозитория то же самое — uv run bsl-ctx …); артефакты по умолчанию пишутся в каталог данных.

# 1. корпус справки из установленной платформы → каталог данных/corpus.sqlite
uvx bsl-ctx capture /opt/1cv8/x86_64/8.3.27.1688

# 2. (опционально) дамп «Инструментов разработчика» → каталог данных/dump
uvx bsl-ctx ir-dump RDT1C/ -o ~/.local/share/bsl-ctx/dump
uvx bsl-ctx validate-dump ~/.local/share/bsl-ctx/dump

# 3. БД продукта (без шага 2 — уберите --dump)
uvx bsl-ctx build \
    --corpus ~/.local/share/bsl-ctx/corpus.sqlite \
    --db ~/.local/share/bsl-ctx/bsl-context-8.3.27.1688.sqlite \
    --dump ~/.local/share/bsl-ctx/dump

# 4. проверить и подключить
uvx bsl-ctx doctor --db ~/.local/share/bsl-ctx/bsl-context-8.3.27.1688.sqlite
uvx bsl-ctx serve --db ~/.local/share/bsl-ctx/bsl-context-8.3.27.1688.sqlite

Шесть инструментов

У агента шесть инструментов (команды CLI зовут те же функции как bsl-ctx <name>; имена совпадают, кроме platform_info, который в CLI пишется через дефис — platform-info). Каждый отдаёт и компактный Markdown (content), и структурированный JSON (structuredContent) из одного результата.

Поток работы агента: search → ref → describe/members/signature/relations.

Пример ответа search "хеш SHA256 от файла":

**7 найдено** (слой: relaxed; отброшено: «от») — показано 7
1. `member:6010` **SHA256** — member (ХешФункция) с 8.3.3  score 21
2. `type:1276` **ХешированиеДанных** — type с 8.3.1  score 18
…

Почему БД не в комплекте

Контент справки 1С:Предприятие проприетарен и не попадает в репозиторий. Модель распространения — «каждый генерит свою БД»: публичны только инструменты (этот проект), а не собранные данные. Поэтому распространять готовый bsl-context.sqlite нельзя — но собрать его из своей установки платформы можно командой setup выше.

Источник установки

Печатаемая setup команда подключения берёт значение --from в порядке: флаг --from самой команды, переменная BSL_CTX_INSTALL_SOURCE, умолчание — имя пакета в PyPI без закрепления версии (.mcp.json не меняется при обновлениях). Переменную задают для локальных проверок: путь к собранному колесу или git-URL — тогда и напечатанная команда подключения будет ссылаться на этот источник.

Лицензия и атрибуция

MIT — см. LICENSE. Проект опирается на знание формата .hbk, ранее разобранное в mcp-bsl-platform-context (MIT, © 2025 alkoleft). Данные описания платформы (девять таблиц: контексты, параметры, общие типы, коллекции, расширения, слова языка запросов, сокращения имён) и пары «единственное ↔ множественное» имя объекта метаданных берутся из макетов ирПлатформа/Templates и модуля ирКэш конфигурации «Инструменты разработчика» tormozit'ы (MIT, © 2007–2026 С. А. Старых, https://github.com/tormozit/RDT1C) — как статический снимок, без живого прогона 1С. ИР не модифицируется и её частью проект не является.

Разработка (для контрибьюторов)

uv sync                    # зависимости (включая dev-группу)
uv run pytest              # юнит-тесты на синтетических контейнерах
uv run pytest -m platform  # интеграционные на локальной платформе (опционально)
uv run ruff check          # линтер
uv run mypy                # строгая проверка типов (src/)

Полная архитектура — docs/architecture.md. Интеграционные тесты скипаются без каталога платформы (BSL_CTX_PLATFORM_DIR или pytest --platform-dir).

Выпуск релиза (для сопровождающего)

uv build      # dist/bsl_ctx-<версия>-py3-none-any.whl + sdist
uv publish    # токен: pypi.org → Account settings → API tokens

Токен передаётся флагом --token или переменной UV_PUBLISH_TOKEN. Перед выпуском поднять версию в pyproject.toml — единственный источник, __version__ читается из метаданных пакета — и добавить запись в CHANGELOG.md.