Metadata-Version: 2.5
Name: bsl-ctx
Version: 1.3.1
Summary: Точная справка по платформе 1С для агента-разработчика: ETL корпуса справки + MCP-сервер.
Project-URL: Homepage, https://github.com/ska4win/1C_man_mcp
Project-URL: Repository, https://github.com/ska4win/1C_man_mcp
Project-URL: Issues, https://github.com/ska4win/1C_man_mcp/issues
Project-URL: Documentation, https://github.com/ska4win/1C_man_mcp/blob/main/docs/architecture.md
Author-email: ska4win <ska4winturk@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: 1c,1c-enterprise,bsl,hbk,mcp,syntax-help
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Requires-Dist: mcp<3,>=2
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# bsl-ctx

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

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

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

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

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

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

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

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

```bash
uvx bsl-ctx setup
```

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

```bash
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` (любой клиент). Путь к собранной БД подставляется автоматически.

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

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

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

| команда | что делает |
|---|---|
| `bsl-ctx list` | собранные БД с версиями и размерами |
| `bsl-ctx clean [--all]` | удалить промежуточное (corpus, дамп ИР); `--all` — и БД |

Каталог данных переопределяется переменной `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 …`); артефакты по умолчанию пишутся в каталог данных.

```bash
# 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` | Поиск по естественной формулировке. Если все токены вместе ничего не находят, ослабляет запрос (отбрасывает служебные/частые слова) и помечает результат `layer: "relaxed"` с `dropped: […]` — агент видит, что ответ на укороченный вопрос. |
| `describe` | Карточка сущности по `ref` или имени: описание, сигнатуры, доступность, пример, версии, устаревание. Поля ИР (`guid`, доступ по индексу, доступность по средам) — только когда есть. |
| `members` | Члены типа (методы/свойства/события) с пагинацией и фильтром. |
| `signature` | Перегрузки сигнатуры: параметры с типами, возвращаемое значение. |
| `relations` | Связи типа: что возвращает, элементом какой коллекции является, какой тип расширяет (`base`) и кто его расширяет (`extensions`). |
| `platform_info` | Самоориентация: версия платформы, схема, счётчики, стабильность `ref`. |

Поток работы агента: `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 с закреплённой версией. Переменную задают для локальных проверок: путь к
собранному колесу или git-URL — тогда и напечатанная команда подключения будет
ссылаться на этот источник.

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

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

---

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

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

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

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

```bash
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`.
