rlm-tools-bsl

# 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 — workshop for AI-agents working with 1C" width="720"> </p> [](https://github.com/Dach-Coin/rlm-tools-bsl/actions/workflows/ci.yml) [](https://pypi.org/project/rlm-tools-bsl/) [](https://www.python.org/downloads/) [](https://github.com/Dach-Coin/rlm-tools-bsl/actions/workflows/ci.yml) [](LICENSE) MCP Server for token-efficient analysis of 1C code bases (BSL). Adaptation of the open-source project [rlm-tools](https://github.com/stefanoshea/rlm-tools) to the specifics of the 1C:Enterprise platform — large code bases, source file formats (CF/EDT), metadata structure, Cyrillic code, XML object descriptions. > 📖 Publication on Infostart: <a href="https://infostart.ru/1c/articles/2707750/"><img src="https://raw.githubusercontent.com/Dach-Coin/rlm-tools-bsl/master/docs/assets/infostart-logo.svg" alt="Infostart" height="20" align="absmiddle"></a> [«rlm-tools-bsl — workshop for AI-agents working with 1C»](https://infostart.ru/1c/articles/2707750/) ## Installation **Windows — installation + service in one command** (PowerShell as administrator): ```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 ``` The script will install the package from PyPI, register the Windows service, start the server, and check health. Re-running will update to the latest version. > **If the service does not start** (error 1053, etc.) — see [Windows Service Diagnostics](docs/INSTALL.md#windows-service-diagnostics). **Linux — installation + systemd service in one command:** ```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 # Edit REPOS_ROOT and other variables docker compose up -d ``` The container automatically updates the **package** from PyPI (if the version in PyPI is higher than the current one in the container) at each start (registered project indices are not recalculated by default; enabled by `RLM_UPDATE_INDEX_ON_START=1`). To run from local sources: `uv build` before `docker compose up -d --build`. Details: **[docs/INSTALL.md](docs/INSTALL.md#variant-b-docker)** > **Windows + Docker Desktop:** not recommended — I/O through WSL2/Virtiofs is 5-10x slower than native. Indexing and helper work will *significantly* slow down. Use host installation (pip/service). Docker is optimal for **Linux**. ### From sources (for development) **Requirements:** Python 3.10+, [uv](https://github.com/astral-sh/uv) (package manager). LLM keys are optional — basic functionality works without them. #### Windows (PowerShell as administrator) ```powershell git clone https://github.com/Dach-Coin/rlm-tools-bsl.git cd rlm-tools-bsl PowerShell -ExecutionPolicy Bypass -File .\simple-install.ps1 ``` The script is idempotent: re-running after `git pull` stops the service, cleans up stale artifacts, rebuilds the package, and restarts the server. #### 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 ``` The scripts will install the package, register the service, start the server, and check endpoint availability. ### Config for AI-client After installation, add to `.claude.json` / `mcp.json`: ```json { "mcpServers": { "rlm-tools-bsl": { "type": "http", "url": "http://127.0.0.1:9000/mcp" } } } ``` > `"type": "http"` is required for most clients (Claude Code, Kilo Code, Roo Code, Cursor). Stdio connection also works, but HTTP is recommended. --- ## Main philosophy and purpose of the product Get search by BSL code base for AI-assistant, comparable in quality to RAG, but without RAG itself (and its time costs on preliminary vectorization) and with significant token and context savings for analysis <p align="center"> <img src="https://raw.githubusercontent.com/Dach-Coin/rlm-tools-bsl/master/docs/assets/rlm-tools-bsl-agent-flow.png" alt="Scheme of AI-agent work with rlm-tools-bsl" width="720"> </p> ## RAG and RLM — what is it **RAG** (Retrieval-Augmented Generation) — approach where before generating a response, LLM first searches for relevant fragments from a pre-indexed knowledge base (embeddings, dependency graph, full-text search). Requires preliminary indexing, infrastructure, and maintenance. **RLM** (Repository-Level Machine-coding) — approach where AI-agent directly explores the repository: performs search queries, reads files, analyzes structure — all in real-time, without preliminary vector indexing. ## Why RLM is needed on top of built-in AI-assistant tools AI-assistants (Claude Code, Cursor, Windsurf, etc.) already know how to read files and search by code through built-in grep/read/glob. But each call returns **raw data entirely** directly to the agent's context window: full files, long lists of matches, directory trees. On large 1C configurations (20,000+ files), the context gets clogged after several requests. **rlm-tools-bsl solves this problem:** the agent sends a Python script to the server (host where the project is open), the script runs in a sandbox, and only `print()` — compact filtered result instead of raw data — is returned to the context. Example: instead of reading a 2000-line file entirely (2000 lines in context), the agent calls `extract_procedures(path)` and gets a list of 15 signatures. Then `read_procedure(path, "ОбработкаПроведения")` — and gets the body of one needed procedure. **Typical savings — 25-95% of context.** ## RLM — not a replacement for RAG, but a complement RLM does not compete with RAG. These are different tools for different situations. **RAG** — is a loom at a factory: powerful, productive, produces industrial-quality fabrics and clothing. But requires a room, setup, maintenance, and time to launch. **RLM** — is a home sewing machine: compact, always at hand, can be taken with you. Won't replace a factory, but doesn't require one either. Hem, alter, figure out a pattern — quickly and without preparation. Or, if closer to an automotive analogy: **RAG** — a huge dealership: a warehouse on thousands of square meters, a team of masters in uniform, any part can be found. But until they schedule, accept, and conduct a routine diagnostic — a day is gone. And the bill at the end for work is impressive. **RLM** — a specialized auto service at home: drove in without an appointment, the master immediately under the hood, sorted out exactly your problem and released. Without rare parts from another continent — but for everyday tasks faster, cheaper, and more accurate. Use both approaches where each is stronger. ## When to use ### Case 1: «Understand a new configuration» Given a new extension or 1C configuration and asked: «Figure out how this subsystem works» or «What needs to be modified to add a new document». Raising RAG for a one-time task is not feasible — indexing will take hours, and the answer is needed now. With rlm-tools-bsl: specified the path to the source directory — and the agent is already working. ### Case 2: «Evaluate implementation» Sent a target configuration and a list of business requirements, they ask to quickly prepare an assessment: which objects are affected, what will require development, where is ready-made functionality. Deploying infrastructure for one assessment is redundant. RLM allows the agent to walk through the source code, find the necessary modules and metadata, and form an assessment in one session. ### Case 3: «Check team code every day» You are a project development team lead through a 1C storage repository (synchronized with Git via [gitsync](https://github.com/oscript-library/gitsync)). Many commits in the repository every day (synchronized with Git). RAG reindexes on a schedule once or twice a week — it takes a long time, and you need to check the team's code daily. RLM works with actual files on disk: synchronized storage (downloaded to sources) → agent immediately sees fresh code. ### Case 4: "Many Active Databases - No Time to Index" You are a developer with three or more large 1C databases in active development. Users and analysts constantly come with questions, and raising and maintaining a RAG index for each database is expensive and time-consuming. Simply point `llm` and `rlm-tools-bsl` to the directory with the source code of the desired database - and answer questions without any preliminary preparation. ### Case 5: "Features Implemented - Now Need Documentation" You are a developer who has been making improvements for a long time but did not write documentation and descriptions of "how it works". Now the team lead or architect requires a description, and there is no RAG index on your code yet. Simply point `rlm-tools-bsl` to the source code of your development database and ask LLM to write technical descriptions directly from the code. ### Case 6: "Analyst on a New Project without RAG" You are an analyst who has been given someone else's database and several subordinate users with constant questions "how to do this in the program, how to do that". There is no RAG on the project. Simply point `llm` and `rlm-tools-bsl` to the source code of the database - and get ready-made answers to users, without manually browsing the code and without bothering developers. ### Also suitable if: - You need to analyze a specific subsystem, mechanism, or block of custom improvements - You work with any format of source code: CF (download from Configurator), EDT (1C:EDT), MDO - The configuration is large (20K+ files) and you cannot feed everything into the context of one session - Previously, you collected and prepared context (modules, graph/stack of calls, requirements) manually and want to make your life a little easier - You plan to search through the code base with deterministic questions ("tell me how the document AdvanceReport works", "find the http-service ExchangeWithCorporateSegments, describe its methods", etc.) ## When NOT to use - You need a **complete** dependency graph of all configuration objects - for this, you need RAG/graph MCP with preliminary indexing. But for point analysis of a specific object, the `find_callers_context` helper builds a graph of **BSL calls** on the fly, and the `find_references_to_object` helper (analog of the command in the configurator "Find references → In properties") instantly shows all **references to the metadata object** from 18 different sources (attributes, subsystems, exchange plans, functional options, owners, DefinedTypes, roles, commands, etc.). The `find_defined_types` helper reveals `DefinedType` in a list of real types - You need semantic search by object descriptions - `rlm-tools-bsl` searches by files and names, not by embeddings - Vague non-deterministic questions ("how budgeting works in ERP", "how cellular warehouses work in Retail") - for this, you need a full-fledged RAG (or analyze using SOTA models, as they can convert fuzzy semantics into strict full-text queries to the 1C code base through `rlm-tools-bsl`) ## Actual (e2e) comparison with RAG/graph approach Comparative testing (April 2026) of 6 MCP servers on the 1C:Document Flow CORP 3.0 configuration - 10 business tasks × 6 servers = 60 agent launches. Methodology, prompts, and results: **[perform_comparison_1c_rag_mcp](https://github.com/Dach-Coin/perform_comparison_1c_rag_mcp)**. | Server | Quality | Avg tokens | Type | License | | --------------------- | :------: | :--------: | :---: | :--------: | | **rlm-tools-bsl** | 10/10 | 117K | RLM | free | | code-metadata (08.04) | 10/10 | 179K | RAG | paid | | 1c-mcp-metacode | 10/10 | 264K | graph | free | | code-metadata (07.04) | 7/10 | 206K | RAG | paid | | graph-metadata | 5/10 | 538K | graph | paid | | cloud-embeddings | 4/10 | 265K | RAG | paid | **Conclusions:** - Three servers scored a maximum of 10/10: `rlm-tools-bsl`, code-metadata 08.04, and 1c-mcp-metacode - while `rlm-tools-bsl` consumed a minimum of tokens (117K) and does not require infrastructure (docker + lm-studio). - The code-metadata 08.04 version rose from 7/10 to 10/10, including after adding full-text search mechanisms, **[borrowed](https://docs.onerpa.ru/mcp-servers-1c/servery/code-metadata-search#dopolnitelno-rlm-tools-bsl-rlm-podkhod)** from `rlm-tools-bsl`. ### Preliminary indexing (optional but desirable) To speed up work on large configurations, you can pre-build an SQLite index of methods and call graph - see **[docs/INDEXING.md](docs/INDEXING.md)**. On PCs with slow disks (HDD, network resources), indexing is practically mandatory: without an index, file operations on configurations of ERP size (20K+ BSL files) lead to timeouts (60-90s for each `glob_files`/`tree`/`find_files` call). In addition to acceleration, pre-created indexes help weak models (Minimax, Gemini Flash, etc.) perform high-quality analysis on large code bases - instant helper responses instead of timeouts eliminate the main cause of errors. Searches for references to 1C metadata objects, connections, attribute types, etc. - without pre-built indexes, answers to such queries will be inaccurate and noisy. **The presence of a `.git` directory in 1C source code (and Git installed on the host with rlm) significantly enhances search.** If the source code directory is under git, the `git_search` killer feature is automatically activated - a full-text engine `git grep` across all configuration files. These are powerful capabilities specifically for "non-subject" search: any terms, GUID/numbers, user messages, code snippets, string literals, XML attributes of forms/rights/SKD, arbitrary technical markers - all that cannot be expressed as "find MD object", "find procedure", "find attribute". Searches including in "raw" `.xml`/`.mdo` and texts unavailable to ordinary helpers and rlm-index; included natively, without rebuilding the rlm-index. Read more - **[docs/INDEXING.md](docs/INDEXING.md)**. ## Project registry Instead of remembering absolute paths to source code, you can register projects by names: ``` rlm_projects(action="add", name="My Config", path="/path/to/1c-sources", password="МойПароль") rlm_start(project="My Config", query="find module...") ``` Password is required when registering a project. It will be required when managing indexes through the mcp-tool `rlm_index(build/update/drop)` and during any mutating operations with the registry (remove/update/rename - `password` parameter). The model will request the password from the user. This is required so that the AI assistant does not perform operations without instructions and confirmation from a person. The CLI interface `rlm-bsl-index` does not require a password. The registry is stored in `projects.json` next to `service.json`. Read more - **[docs/PROJECT_REGISTRY.md](docs/PROJECT_REGISTRY.md)** ## How it works (under the hood) Six MCP tools (`rlm_projects`, `rlm_index`, `rlm_start` → `rlm_help` → `rlm_execute` → `rlm_end`), sandbox with **59 helpers** (49 BSL-specific + 8 standard + 2 LLM), session caches, timeouts, security, example of building a call graph on a large configuration (23K+ files) - **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** Full list of helpers - **[docs/HELPERS.md](docs/HELPERS.md)** | Joint use with RAG - **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#совместное-использование-с-rag)** Module and dependency map - **[docs/MODULE_MAP.md](docs/MODULE_MAP.md)** | Internal developer checklists - **[docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md)** ## Compatibility with original rlm-tools The entire functionality of the original [rlm-tools](https://github.com/stefanoshea/rlm-tools) is preserved. BSL functionality is added on top, without breaking the original mechanics. Read more - **[docs/HELPERS.md](docs/HELPERS.md#совместимость-с-оригинальным-rlm-tools)** ## Setting up llm_query (optional) In the sandbox, there are helpers `llm_query(prompt, context)` and `llm_query_batched(prompts, context)` - they call a "small" LLM directly from `rlm_execute`, without returning to the main agent context. This allows you to classify, filter, and summarize data on the server side, saving the context consumption of the main model. OpenAI-compatible endpoints (OpenRouter, Ollama, vLLM) and Anthropic API are supported. Without LLM setup, all other helpers work normally. Detailed setup, mechanics, quotas, and examples - **[docs/LLM_QUERY.md](docs/LLM_QUERY.md)** | All environment variables - **[docs/ENV_REFERENCE.md](docs/ENV_REFERENCE.md)** ## Session Start Modes: `slim` (default) or `full` `rlm_start` defaults to the **slim** strategy — a compact roadmap of the sandbox toolkit. Detailed recipes and helper descriptions are loaded on demand via the MCP tool `rlm_help(...)`. This saves context tokens at session start: the full strategy includes ~20K characters of inline documentation, while slim is 3.5–4 times smaller. If you notice poor analysis quality and the agent is struggling to choose helpers (especially for weaker models like Haiku or small OSS), try restarting the server with `RLM_STRATEGY_MODE=full`: the strategy format is entirely inline (all recipes and descriptions are loaded at start), and the `rlm_help` tool is removed from the MCP server manifest. For details, see **[docs/ENV_REFERENCE.md](docs/ENV_REFERENCE.md)** (section "rlm_start Strategy"). For detailed instructions (service configuration, .env, stdio, development): **[docs/INSTALL.md](docs/INSTALL.md)** > **All deployment scenarios and example setup from scratch:** > **[docs/QUICKSTART.md](docs/QUICKSTART.md)** > > **Frequently Asked Questions (CFE extensions, passwords, Docker, token usage, multiple projects):** > **[docs/FAQ.md](docs/FAQ.md)** ## Instructions for the Analyzer Agent (Quality Report Enhancer) A ready-to-use block of rules to insert into your AI assistant instructions (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, system prompt, etc.) — **[docs/AGENT_INSTRUCTIONS.md](docs/AGENT_INSTRUCTIONS.md)**. This sets the agent's discipline for working with `rlm-tools-bsl`: load `rlm_help` recipes before work, batch calls tightly, check the index, take facts only from read data (not from object names), calculate composition programmatically, fetch missing data in full text, and perform final verification. In practice, this significantly improves report completeness and accuracy and reduces token consumption — especially for weaker models. ## Testing on Real Data Before each new release, testing is performed on: - The BSL codebase of the improved ERP 2.5 (output format - configurator). - The BSL codebase of the improved ERP 2.4 (output format - EDT). - The BSL codebase of the improved DO 3 (output format - configurator). - BSL dumps of extensions in both formats. Ready-to-use prompts for comprehensive E2E tests of BSL helpers: **[docs/full_analysis_prompt.md](docs/full_analysis_prompt.md)** ## License MIT (inherited from [rlm-tools](https://github.com/stefanoshea/rlm-tools)) ## Changelog Release history: [CHANGELOG.md](CHANGELOG.md)