Metadata-Version: 2.4
Name: rlm-tools-bsl
Version: 1.9.2
Summary: MCP server for token-efficient 1C BSL codebase analysis
Project-URL: Homepage, https://github.com/Dach-Coin/rlm-tools-bsl
Project-URL: Repository, https://github.com/Dach-Coin/rlm-tools-bsl
Project-URL: Issues, https://github.com/Dach-Coin/rlm-tools-bsl/issues
Project-URL: Changelog, https://github.com/Dach-Coin/rlm-tools-bsl/blob/master/CHANGELOG.md
Author: Dach-Coin
License: MIT License
        
        Copyright (c) 2026 Stefan O'Shea (original rlm-tools)
        Copyright (c) 2026 Roman Starchenko (rlm-tools-bsl)
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: 1c,ai-tools,bsl,code-analysis,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.40.0
Requires-Dist: mcp[cli]>=1.2.0
Requires-Dist: openai>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: service
Requires-Dist: pywin32>=306; (sys_platform == 'win32') and extra == 'service'
Description-Content-Type: text/markdown

# rlm-tools-bsl

<p align="center">
  <img src="https://raw.githubusercontent.com/Dach-Coin/rlm-tools-bsl/master/docs/assets/rlm-tools-bsl-cover.png" alt="rlm-tools-bsl — мастерская для AI-агентов, работающих с 1С" width="720">
</p>

[![CI](https://github.com/Dach-Coin/rlm-tools-bsl/actions/workflows/ci.yml/badge.svg)](https://github.com/Dach-Coin/rlm-tools-bsl/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/rlm-tools-bsl.svg)](https://pypi.org/project/rlm-tools-bsl/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![Coverage](https://img.shields.io/badge/coverage-81%25-brightgreen.svg)](https://github.com/Dach-Coin/rlm-tools-bsl/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

MCP-сервер для токен-эффективного анализа кодовых баз 1С (BSL).

Адаптация open-source проекта [rlm-tools](https://github.com/stefanoshea/rlm-tools) под специфику платформы 1С:Предприятие — большие кодовые базы, форматы исходников (CF/EDT), структура метаданных, кириллический код, XML-описания объектов.

## Установка

**Windows — установка + служба одной командой** (PowerShell от имени администратора):

```powershell
irm https://raw.githubusercontent.com/Dach-Coin/rlm-tools-bsl/master/simple-install-from-pip.ps1 -OutFile simple-install-from-pip.ps1
PowerShell -ExecutionPolicy Bypass -File .\simple-install-from-pip.ps1
```

Скрипт установит пакет из PyPI, зарегистрирует Windows-службу, запустит сервер и проверит health. Повторный запуск — обновление до последней версии.

> **Если служба не запускается** (ошибка 1053 и т.п.) — см. [Диагностика Windows-службы](docs/INSTALL.md#диагностика-windows-службы).

**Linux — установка + systemd-служба одной командой:**

```bash
curl -LO https://raw.githubusercontent.com/Dach-Coin/rlm-tools-bsl/master/simple-install-from-pip.sh
chmod +x simple-install-from-pip.sh && ./simple-install-from-pip.sh
```

### Docker

```bash
cp docker-compose.example.yml docker-compose.yml
# Отредактируйте REPOS_ROOT и другие переменные
docker compose up -d
```

Контейнер автоматически обновляется из PyPI при каждом старте. Для запуска из локальных исходников: `uv build` перед `docker compose up -d --build`. Подробности: **[docs/INSTALL.md](docs/INSTALL.md#вариант-b-docker)**

> **Windows + Docker Desktop:** не рекомендуется — I/O через WSL2/Virtiofs в 5-10x медленнее нативного. Индексирование и работа хелперов будут *значительно* тормозить. Используйте установку на хост (pip/служба). Docker оптимален для **Linux**.

### Из исходников (для разработки)

**Требования:** Python 3.10+, [uv](https://github.com/astral-sh/uv) (пакетный менеджер). LLM-ключи опциональны — без них работает базовый функционал.

#### Windows (PowerShell от имени администратора)

```powershell
git clone https://github.com/Dach-Coin/rlm-tools-bsl.git
cd rlm-tools-bsl
PowerShell -ExecutionPolicy Bypass -File .\simple-install.ps1
```

Скрипт идемпотентен: повторный запуск после `git pull` останавливает службу, очищает stale-артефакты, пересобирает пакет и перезапускает сервер.

#### Linux

```bash
git clone https://github.com/Dach-Coin/rlm-tools-bsl.git
cd rlm-tools-bsl
chmod +x simple-install.sh && ./simple-install.sh
```

Скрипты установят пакет, зарегистрируют службу, запустят сервер и проверят доступность endpoint'а.

### Конфиг для AI-клиента

После установки добавьте в `.claude.json` / `mcp.json`:

```json
{
  "mcpServers": {
    "rlm-tools-bsl": {
      "type": "http",
      "url": "http://127.0.0.1:9000/mcp"
    }
  }
}
```

> `"type": "http"` обязателен для большинства клиентов (Claude Code, Kilo Code, Roo Code, Cursor). Подключение по stdio тоже работает, но HTTP рекомендуется.

Подробная инструкция (конфигурация сервиса, .env, stdio, разработка): **[docs/INSTALL.md](docs/INSTALL.md)**

> **Все сценарии развёртывания и пример настройки с нуля:**
> **[docs/QUICKSTART.md](docs/QUICKSTART.md)**
>
> **Часто задаваемые вопросы (расширения CFE, пароли, Docker, расход токенов, несколько проектов):**
> **[docs/FAQ.md](docs/FAQ.md)**

---

## Основная философия и предназначение продукта
Получить для AI-ассистента поиск по кодовой базе BSL, сопоставимый по качеству с RAG, но при этом без самого RAG и при масштабной экономии токенов и контекста на анализ

## RAG и RLM — что это

**RAG** (Retrieval-Augmented Generation) — подход, при котором перед генерацией ответа LLM сначала ищет релевантные фрагменты из заранее проиндексированной базы знаний (эмбеддинги, граф зависимостей, полнотекстовый поиск). Требует предварительной индексации, инфраструктуры и обслуживания.

**RLM** (Repository-Level Machine-coding) — подход, при котором AI-агент исследует репозиторий напрямую: выполняет поисковые запросы, читает файлы, анализирует структуру — всё в реальном времени, без предварительной векторной индексации.

## Зачем нужен RLM поверх встроенных готовых инструментов AI-ассистентов

AI-ассистенты (Claude Code, Cursor, Windsurf и др.) уже умеют читать файлы и искать по коду через встроенные grep/read/glob. Но каждый вызов возвращает **сырые данные целиком** прямо в контекстное окно агента: полные файлы, длинные списки совпадений, деревья каталогов. На больших конфигурациях 1С (20 000+ файлов) контекст забивается за несколько запросов.

**rlm-tools-bsl решает эту проблему:** агент отправляет Python-скрипт на сервер (хост, где открыт проект), скрипт выполняется в песочнице, а в контекст возвращается **только `print()`** — компактный отфильтрованный результат вместо сырых данных.

Пример: вместо того чтобы прочитать файл на 2000 строк целиком (2000 строк в контекст), агент вызывает `extract_procedures(path)` и получает список из 15 сигнатур. Затем `read_procedure(path, "ОбработкаПроведения")` — и получает тело одной нужной процедуры. **Типичная экономия — 25-95% контекста.**

## RLM — не замена RAG, а дополнение

RLM не конкурирует с RAG. Это разные инструменты для разных ситуаций.

**RAG** — это ткацкий станок на фабрике: мощный, производительный, выдаёт ткани и одежду промышленного качества. Но требует помещения, настройки, обслуживания и времени на запуск.

**RLM** — это домашняя швейная машинка: компактная, всегда под рукой, можно взять с собой. Не заменит фабрику, но и не требует её. Подшить, перекроить, разобраться в выкройке — быстро и без подготовки.

Или, если ближе автомобильная аналогия:

**RAG** — огромный дилерский центр: склад на тысячи квадратных метров, штат мастеров в одинаковой форме, любая запчасть найдётся. Но пока запишут, пока примут, пока пройдут регламентную диагностику — день ушёл. И счёт в конце впечатляет.

**RLM** — специализированный автосервис у дома: заехал без записи, мастер сразу под капот, разобрался именно с вашей проблемой и отпустил. Без редких запчастей с другого континента — но для повседневных задач быстрее, дешевле и точнее.

Используйте оба подхода там, где каждый сильнее.

## Когда использовать

### Кейс 1: «Разберись в новой конфигурации»

Дали новое расширение или конфигурацию 1С и задали вопрос: «Разберись, как работает вот эта подсистема» или «Что нужно доработать, чтобы добавить новый документ». Поднимать RAG ради разовой задачи нецелесообразно — индексация займёт часы, а ответ нужен сейчас. С rlm-tools-bsl: указал путь к каталогу исходников — и агент уже работает.

### Кейс 2: «Оцени внедрение»

Прислали целевую конфигурацию и список бизнес-требований, просят быстро подготовить оценку: какие объекты затронуты, что потребует доработки, где готовая функциональность. Разворачивать инфраструктуру для одной оценки — избыточно. RLM позволяет агенту пройтись по исходникам, найти нужные модули и метаданные, и сформировать оценку за один сеанс.

### Кейс 3: «Проверяй код команды каждый день»

Ты — тимлид проекта разработки через хранилище 1С. Много коммитов в хранилище каждый день (синхронизируемое с Git через [gitsync](https://github.com/oscript-library/gitsync)). RAG переиндексируется по расписанию раз-два в неделю — ждать долго, а проверять код команды нужно ежедневно. RLM работает по актуальным файлам на диске: синхронизировал хранилище → агент сразу видит свежий код.

### Кейс 4: «Много активных баз — некогда индексировать»

Ты — разработчик, у которого три и более крупных баз 1С в активной разработке. Пользователи и аналитики постоянно приходят с вопросами, а поднимать и обслуживать RAG-индекс для каждой базы — дорого и долго. Просто указываешь llm + rlm-tools-bsl на каталог с исходниками нужной базы — и отвечаешь на вопросы без какой-либо предварительной подготовки.

### Кейс 5: «Запилил фичи — теперь нужна документация»

Ты — разработчик, который долго делал доработки, но не писал документацию и описания «как это работает». Теперь тимлид или архитектор требует описания, а RAG-индекса на твой код ещё нет. Просто указываешь rlm-tools-bsl на исходники своей дев-базы и просишь LLM написать технические описания прямо по коду.

### Кейс 6: «Аналитик на новом проекте без RAG»

Ты — аналитик, которому дали чужую базу и несколько подшефных пользователей с постоянными вопросами «а как в программе сделать то, а как это». RAG на проекте нет. Просто указываешь llm + rlm-tools-bsl на исходники базы — и получаешь готовые ответы пользователям, не листая код вручную.

### Ещё подходит, если:

- Нужно проанализировать конкретную подсистему, механизм или блок кастомных доработок
- Работаешь с любым форматом исходников: CF (выгрузка из Конфигуратора), EDT (1C:EDT), MDO
- Конфигурация большая (20K+ файлов) и нельзя скормить всё в контекст одной сессии
- Раньше ты собирал и готовил контекст (модули, граф/стек вызовов, требования) руками и хочешь хотя бы немного облегчить себе жизнь
- Ты планируешь искать по кодовой базе с детерминированными вопросами ("расскажи как работает проведение документа АвансовыйОтчет", "найди http-сервис ОбменСКорпоративнымиСегментами, опиши его методы" и т.д.)

## Когда НЕ использовать

- Нужен **полный** граф зависимостей всех объектов конфигурации — для этого нужен RAG/графовый MCP с предварительной индексацией. Для точечного анализа конкретного объекта `find_callers_context` строит граф **BSL-вызовов** на лету, а `find_references_to_object` (v1.9.0, аналог конфигуратора «Найти ссылки → В свойствах») мгновенно показывает все **ссылки на объект метаданных** из 18 разных источников (реквизиты, подсистемы, планы обмена, функциональные опции, владельцы, ОпределяемыеТипы, роли, команды и т.д.). `find_defined_types` раскрывает `ОпределяемыйТип` в список реальных типов
- Нужен семантический поиск по описаниям объектов — rlm-tools-bsl ищет по файлам и именам, не по эмбеддингам
- Нечёткие недетерминированные вопросы («как работает бюджетирование в ЕРП», «как работают ячеистые склады в УТ») — для этого нужен полноценный RAG

## Сравнение с RAG/графовым подходом

Сравнительное тестирование 6 MCP-серверов на конфигурации 1С:Документооборот КОРП 3.0 — 10 бизнес-задач × 6 серверов = 60 агентских запусков (апрель 2026). Методология, промпты и результаты: **[perform_comparison_1c_rag_mcp](https://github.com/Dach-Coin/perform_comparison_1c_rag_mcp)**.

| Сервер                | Качество | Avg tokens |  Тип  |  Лицензия  |
| --------------------- | :------: | :--------: | :---: | :--------: |
| **rlm-tools-bsl**     |  10/10   |    117K    |  RLM  | бесплатный |
| code-metadata (08.04) |  10/10   |    179K    |  RAG  |  платный   |
| 1c-mcp-metacode       |  10/10   |    264K    | graph | бесплатный |
| code-metadata (07.04) |   7/10   |    206K    |  RAG  |  платный   |
| graph-metadata        |   5/10   |    538K    | graph |  платный   |
| cloud-embeddings      |   4/10   |    265K    |  RAG  |  платный   |

**Выводы:**

- Три сервера набрали максимум 10/10: rlm-tools-bsl, code-metadata 08.04 и 1c-mcp-metacode — при этом rlm-tools-bsl потребил минимум токенов (117K) и не требует инфраструктуры.
- Версия code-metadata 08.04 поднялась с 7/10 до 10/10 в том числе после добавления механизмов полнотекстового поиска, [заимствованных](https://docs.onerpa.ru/mcp-servery-1c/servery/code-metadata-search#dopolnitelno-rlm-tools-bsl-rlm-podkhod) из rlm-tools-bsl.

### Предварительное индексирование (опционально)

Для ускорения работы на больших конфигурациях можно предварительно построить SQLite-индекс методов и графа вызовов — см. **[docs/INDEXING.md](docs/INDEXING.md)**. На ПК с медленными дисками (HDD, сетевые ресурсы) индексирование фактически обязательно: без индекса файловые операции на конфигурациях размера ERP (20K+ BSL-файлов) приводят к таймаутам (60-90с на каждый вызов `glob_files`/`tree`/`find_files`). Помимо ускорения, предварительно созданные индексы помогают слабым моделям (Minimax, Gemini Flash и др.) выполнять качественный анализ на больших кодовых базах — мгновенные ответы хелперов вместо таймаутов устраняют основную причину ошибок.

## Реестр проектов

Вместо запоминания абсолютных путей к исходникам можно зарегистрировать проекты по именам:

```
rlm_projects(action="add", name="My Config", path="/path/to/1c-sources", password="МойПароль")
rlm_start(project="My Config", query="find module...")
```

Пароль обязателен при регистрации проекта. Он потребуется при управлении индексами через mcp-tool `rlm_index(build/update/drop)` и при любых мутирующих операциях с реестром (remove/update/rename — параметр `password`). Модель запросит пароль у пользователя. Это требуется, чтобы ai-ассистент не выполнял операции без команды и подтверждения со стороны человека. CLI-интерфейс `rlm-bsl-index` не требует пароля.

Реестр хранится в `projects.json` рядом с `service.json`. Подробнее -- **[docs/PROJECT_REGISTRY.md](docs/PROJECT_REGISTRY.md)**

## Как работает (под капотом)

Пять MCP-инструментов (`rlm_projects`, `rlm_index`, `rlm_start` → `rlm_execute` → `rlm_end`), песочница с **53 хелперами**, сессионные кэши, таймауты, безопасность, пример построения графа вызовов на крупной конфигурации (23K+ файлов) — **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**

Полный список хелперов — **[docs/HELPERS.md](docs/HELPERS.md)** | Совместное использование с RAG — **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#совместное-использование-с-rag)**

Карта модулей и зависимостей — **[docs/MODULE_MAP.md](docs/MODULE_MAP.md)** | Внутренние чеклисты разработчика — **[docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md)**

## Совместимость с оригинальным rlm-tools

Весь функционал оригинального [rlm-tools](https://github.com/stefanoshea/rlm-tools) сохранён. BSL-функционал добавлен поверх, не ломая исходную механику. Подробнее — **[docs/HELPERS.md](docs/HELPERS.md#совместимость-с-оригинальным-rlm-tools)**

## Настройка llm_query (опционально)

В песочнице есть хелперы `llm_query(prompt, context)` и `llm_query_batched(prompts, context)` — они вызывают «маленькую» LLM прямо из `rlm_execute`, не возвращаясь в основной контекст агента. Это позволяет классифицировать, фильтровать и суммировать данные на стороне сервера, экономя расход контекста основной модели.

Поддерживаются OpenAI-совместимые endpoint'ы (OpenRouter, Ollama, vLLM) и Anthropic API. Без настройки LLM все остальные хелперы работают нормально.

Подробная настройка, механика, квоты и примеры — **[docs/LLM_QUERY.md](docs/LLM_QUERY.md)** | Все переменные окружения — **[docs/ENV_REFERENCE.md](docs/ENV_REFERENCE.md)**

## Тестирование на реальных данных
Выполнено на BSL-кодовой базе доработанной ERP 2.5 (формат выгрузки - конфигуратор)
Выполнено на BSL-кодовой базе доработанной ERP 2.4 (формат выгрузки - EDT)
Выполнено на BSL-выгрузках расширений в обоих форматах

Готовые промпты для комплексных E2E-тестов BSL-хелперов: **[docs/full_analysis_prompt.md](docs/full_analysis_prompt.md)**

## Лицензия

MIT (наследуется от [rlm-tools](https://github.com/stefanoshea/rlm-tools))

## Changelog

История изменений: [CHANGELOG.md](CHANGELOG.md)
