rlm-tools-bsl 1.7.2

MCP server for token-efficient 1C BSL codebase analysis

rlm-tools-bsl

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

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

Установка

Windows — установка + служба одной командой (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. Повторный запуск — обновление до последней версии.

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

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

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

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

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

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

Windows (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 → PowerShell -ExecutionPolicy Bypass -File .\reinstall-service.ps1

Linux

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:

{
  "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/QUICKSTART.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 — это домашняя швейная машинка: компактная, всегда под рукой, можно взять с собой. Не заменит фабрику, но и не требует её. Подшить, перекроить, разобраться в выкройке — быстро и без подготовки.

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

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

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

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

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

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

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

Ты — тимлид проекта разработки через хранилище 1С. Много коммитов в хранилище каждый день (синхронизируемое с Git через 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 строит граф вызовов на лету
• Нужен семантический поиск по описаниям объектов — rlm-tools-bsl ищет по файлам и именам, не по эмбеддингам
• Нечёткие недетерминированные вопросы («как работает бюджетирование в ЕРП», «как работают ячеистые склады в УТ») — для этого нужен полноценный RAG

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

Данные по результатам тестирования на реальной конфигурации 1С:ERP (23 000+ файлов) - для сравнения использовался шаблонный MCP-сервер 1c-mcp-metacode с индексацией метаданных (не полноценный граф с эмбеддингами, была включена индексация только по шаблонам).

	rlm-tools-bsl	Шаблонный MCP с индексацией*
Время старта	0 сек (указал путь к исходникам — работай)	Часы на индексацию
Инфраструктура	Ничего (только pip/uv install)	БД, сервер индексации (либо docker)
Полнота анализа	Находит объекты, читает код, видит комментарии и историю	Находит то же самое + структурные связи между объектами
Скорость анализа	~8-11 минут	~7-9 минут
Глубина по коду	Читает тела процедур, строит граф вызовов на лету	Тела процедур + граф вызовов из БД
Работа с метаданными	XML-парсинг (реквизиты, ТЧ, ресурсы, измерения)	Полная структура из БД

* В проведенных тестах MCP с индексацией возвращал ~600K символов на задачу против ~91K у rlm-tools-bsl. Однако это особенность конкретной реализации (шаблонный поиск без эмбеддингов, полнотекстовые совпадения). Полноценный графовый MCP с эмбеддингами и чанкированием давал бы значительно более компактные ответы за счёт ранжирования по релевантности.

Вывод: rlm-tools-bsl — это инструмент из серии «поставил и поехал», для быстрого анализа. RAG/графовые решения дают более полную картину (граф зависимостей, семантический поиск), но требуют предварительной подготовки, инфраструктуры, периодического обслуживания. Лучший результат — использовать оба подхода в связке.

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

Для ускорения работы на больших конфигурациях можно предварительно построить SQLite-индекс методов и графа вызовов — см. 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) — модель запросит его у пользователя. Это требуется, чтобы ai-ассистент не выполнял индексирование без команды и подтверждения со стороны человека. CLI-интерфейс rlm-bsl-index не требует пароля.

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

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

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

Полный список хелперов — docs/HELPERS.md | Совместное использование с RAG — docs/ARCHITECTURE.md

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

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

Весь функционал оригинального rlm-tools сохранён. BSL-функционал добавлен поверх, не ломая исходную механику. Подробнее — docs/HELPERS.md

Настройка 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/ENV_REFERENCE.md

Тестирование на реальных данных

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

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

Лицензия

MIT (наследуется от rlm-tools)

Changelog

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