bsl-ai-toolkit

# Tool List ## bsl-ai-toolkit — AI-first Development 1С:Предприятие (Multi-Agent Contour) [](https://github.com/vgtitov/bsl-ai-toolkit/actions/workflows/tests.yml) [](LICENSE) [](CONTRIBUTING.md) [](AGENTS.md) [](https://v8.1c.ru/) [](https://modelcontextprotocol.io/) [](https://www.python.org/) Reusable set of **rules + skills + MCP servers + byte-perfect metadata editing engine + methodology** for AI-assisted development on **1С:Предприятие 8.3 (BSL)**. **Not tied to a specific AI** — works with different AI-agents (Claude Code, Cursor, Copilot, Gemini CLI, Codex, Cline, Windsurf, Aider) through a unified core and thin adapters. Not tied to a specific organization — adapts to any configuration/extension. Principle: **AI does not guess 1С, but works with REAL code and documentation, according to standards, and brings the code to production-ready.** > **Claude Code — first (reference) implementation.** Other agents are connected with minimal adaptation from the common > core (`core/`) — see `adapters/`. Three axes of portability: **AGENTS.md** (rules) + **SKILL.md** (skills) + **MCP** > (tools). Not 1C-Bitrix (this is a CMS on PHP — [separate toolkit](https://github.com/vgtitov/bitrix-ai-toolkit)). ## Idea The entire RU-scene of AI-development 1С («vibe-coding», agents in EDT/Cursor) rests on one thing: **the model hallucinates 1С details** — invents methods, confuses facades (manager/object/query), does not know the composition of the typical and compatibility mode; and forms/ACS/metadata are considered the «last frontier» of generation and are bypassed manually. The lever of the toolkit is **verifiability through tools**: - **`onec-code`** — search by real configuration code and extension (both layers of the contour), not by memory; - **`bsl-ls`** — BSL Language Server diagnostics after each edit; - **`onec_metadata`** — deterministic **byte-perfect** metadata editing (Configurator-XML + EDT `.mdo`/`.dcs`) with **round-trip verify** (loading into the TEST database by platform + repeated unloading = exactly the target diff). This closes the very «last frontier», which the rest bypass; - **`onec-ops`** — operation and performance (TЖ, query plan, APDEX, Zabbix/Prometheus): agentic SWE, not just coding; - **`onec-data`** — access to live data of the IS read-only under the investigated user (honest RLS, masking PDn). Artifacts (CTZ → tech project) are transformed into ordered atomic tasks and verified code. Niche in one phrase: **deterministic, verifiable, and secure AI-development contour 1С over EDT/git — with byte-perfect metadata and operation, agent-agnostic (including limited access to LLM).** ## What distinguishes from neighbors | | What gives | Our emphasis | |---|---|---| | `comol/ai_rules_1c`, `cursor_rules_1c` | rules for LLM | we have rules + **execution through MCP on real code**, not just text instructions | | `Nikolay-Shirokov/cc-1c-skills` | skills for Claude Code for 1С | we have skills **+ metadata engine + operation + multi-agent** | | VibeFlow1C, Shotgun | framework/pipeline vibe-coding | we **infrastructure layer** (MCP+engine), compatible, not competing | | `1c-syntax/bsl-language-server` | syntax/diagnostics | we use as a tool (`bsl-ls`), add code/data context | Unique: **byte-perfect metadata editing with round-trip** (forms/ACS/attributes) — what almost the entire scene recognizes as the «last frontier» and bypasses. ## Composition ``` bsl-ai-toolkit/ ├── core/ # SINGLE SOURCE OF TRUTH (common for all AI-agents) │ ├── AGENTS.md # rules (ask-tool, contour layers, metadata gateway, performance, security) │ ├── skills/ # SKILL.md × 6: 1c-dev · 1c-analyst · 1c-metadata · 1c-admin-devops · 1c-dba · 1c-expert │ └── mcp/servers.json # MCP profile: onec-code · bsl-ls · onec-ops · onec-data (paths/credentials via env) ├── adapters/ # thin adapters for agents (claude — reference; codex/gemini — fallback; cursor/copilot/… — rulesync) │ ├── claude/ # CLAUDE.md (@AGENTS.md) + settings.json (hook bsl_guard) │ └── README.md # matrix «agent → rules file → MCP config» + LLM providers (RF/sanctions) ├── build.sh # generation from core/: CLAUDE.md · AGENTS.md · GEMINI.md · .mcp.json · .claude/ (committed) ├── onec_metadata/ # OS-independent metadata editing engine (Configurator-XML + EDT .mdo/.dcs), byte-perfect │ └── formats/ · ops/ · apply/ · catalog.py # apply-layer (ssh/scp/tar or local) + round-trip verify in TEST database ├── bin/1c-meta # headless CLI engine (detect/template/scd/attr/child) ├── mcp/ # MCP implementations: onec_mcp.py · bsl_ls_mcp.py · onec_ops_mcp.py · onec_data_mcp.py ├── extensions/ai_debug/ # 1C extension for onec-data: HTTP-service (read-only under user, privileged behind gateway) ├── config/ # layers.example.toml (layers/scope) · contours.example.md (database map for 1c-analyst) ├── server/ # server part (central onec-code via HTTP for auth — for team) ├── scripts/ # bsl_guard.py (detector «query in cycle») · git-hooks · switch_source · detect_tools · doctor ├── onboard/ # idempotent bootstrap (onboard.sh/.ps1/.cmd) ├── tests/ # pytest (metadata engine, guard, onec-data, smoke) — 500+ tests └── docs/ # AI_INSTALL_GUIDE · AI_UPDATE · data-access-architecture · testing-ladder · connect · … ``` Generated files from `core/` (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.mcp.json`, `.claude/`) are committed so that the repository works immediately after cloning. Edit `core/` → rebuild `sh build.sh` (do not edit manually generated). ## Cross-platform (really checked) Portability — on both axes: **any AI-agent** and **any developer OS**. | Component | macOS | Linux | Windows | |---|---|---|---| | Metadata engine `onec_metadata`, MCP, `scripts/*` | ✅ Python | ✅ Python | ✅ Python | | Config generation | `sh build.sh` | `sh build.sh` | `build.ps1` (native) or `sh build.sh` (Git Bash) | | Onboarding | `onboard/onboard.sh` | `onboard/onboard.sh` | `onboard/onboard.ps1` (+ `.cmd`) | | Apply-layer (editing to test database) | `ssh`/`scp`/`tar` or local runner | same | same (ssh/tar available in Win10+) or local runner | | Git hooks (`commit-msg`, `pre-commit`) | ✅ | ✅ | ✅ (Git for Windows) | The engine is **pure Python** (without OS dependencies); the apply-layer uses `ssh`/`scp`/`tar` (available on all three OS) or **local runner** without SSH (if the platform is on its own machine). Generated agent configs (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.claude/`) are committed → on any OS, the repository works immediately after cloning. The only Windows-specific is the **1C SERVER**, to which remote application is made; on the developer's machine, the OS does not matter. ## Key principles (methodology) - **Ask a tool, don't guess** — signatures/behavior only by code (`onec-code`) and platform documentation/BSP, not by memory. After editing — `bsl-ls`. Mechanism without verification marks `[to check]`, not «correct». - **Contour layers** — configuration (typical, read-only) + extension; search in BOTH, edit in extension. - **Metadata gateway** — structural edits only through `onec_metadata` under round-trip + scope boundary; cascading destructive (renaming/deletion) — human in 1C:EDT. - **Work cycle (6 steps):** understand and verify → atomic tasks [Developer/IDE]|[AI/code] → non-code instructions → code (reuse-first BSP, efficient, according to `v8-code-style` standards) → checks/tests → package transfer. - **Security/compliance** — secrets and PDn are not transmitted to the model; IS data — read-only under user with masking. ## Supported Agents and Providers Toolkit is **agent-agnostic and provider-agnostic**. Main agents are **Claude Code** (Sonnet 4.5 — best by BSL) and **Cursor**; plus **Codex, Gemini CLI, Copilot, Cline, Windsurf, Aider, Kiro, Roo Code** via `adapters/` + `build.sh`. The rule is simple: any agent that reads the rules (in the style of AGENTS.md / steering) and supports MCP works with the toolkit. Access to LLM from the Russian Federation is limited (`unsupported_region`) — connection via proxy-wrapper API / RU-VDS + own proxy / VPN on the router; domestic (GigaChat, YandexGPT) and self-hosted Chinese — as a fallback. The toolkit does not dictate the provider — access settings are set at the agent environment level. For more information, see `adapters/README.md`, `docs/ACCESS_SETUP.md`. ## What it Works With — Environments, Formats, Storage The toolkit is not tied to a single development environment or code storage method. It works with what you already have. | Environment / Format | Support | |---|---| | **1C:EDT** | yes, main format of sources (`.mdo`/`.dcs`), metadata edits and code right in the EDT project; optionally — MCP plugin for live access to the EDT workspace (see `docs/EDT_SETUP.md`) | | **Configurator** | yes, export format in XML; Configurator batch mode is used for loading, checking, and assembling | | **Configuration Repository** | yes, via export to files: export configuration to sources, work, and load back | | **Main (Typical) Configuration** | yes, read-only, search is performed on it and on the extension simultaneously | | **Extensions** | yes, this is the main layer of edits; assembly and parsing of extensions as `.cfe` | | **External Processing and Reports** | yes, `.epf`/`.erf` in both directions: sources ↔ binary | | **git** | yes, EDT sources in git, work on branches, review via merge requests | | **File Database** | yes, including without publication on the web server — via autonomous server (see `docs/TOOLS.md`) | Metadata edits work in both formats (Configurator-XML and EDT), byte-perfect, with verification in the test database. The storage method (git, Storage) does not affect this: the engine works with source files, and how they got to disk is not important. ## Integrations and Connectors (Already Included) The toolkit is not just about code: adjacent SDLC/exploitation systems are already connectable, and the agent works with them directly. | System | What it Provides | How | |---|---|---| | **Jira** | reading tasks, search by JQL, comments | `scripts/atlassian.py jira issue/search` (read-only token) | | **Confluence** | reading pages/tree, search, **publication** `md → page` | `scripts/atlassian.py conf page/tree/search/publish` | | **Zabbix** | APDEX → trapper-items (`1c.apdex[...]`), metrics/problems/dashboards, performance report and diff | `scripts/apdex_to_zabbix.py`, `scripts/zabbix_perf.py`, MCP `onec-ops` (Zabbix API) | | **Prometheus** | querying 1C/cluster metrics (PromQL) | MCP `onec-ops` (`prometheus_query`) | | **Technological Journal / JR** | parsing TJ (TTIMEOUT/TLOCK/EXCP…), registration journal, APDEX by operations | MCP `onec-ops` (`tech_journal_parse`, `event_log_parse`, `apdex_by_operation`) | | **BSL Language Server** | BSL diagnostics after each edit | MCP `bsl-ls` (included) + auto-downloading `scripts/detect_tools.py` | | **Live Data** | OData + debug service `ai_debug` (read-only, RLS, masking PDn) | MCP `onec-data` (10 tools) | | **Central onec-code** | common team search by 1C code via HTTP for auth (Caddy) | `server/` (docker-compose) + `scripts/switch_source.py` / `set_token.*` | The principle is unified: **the source of truth is a real tool and measurement** (`rac`, TJ, `pg_stat_*`, counters), not model memory. To add a custom connector — a thin script in `scripts/` or a tool in MCP `onec-ops`; secrets — only via env. ## Installation ```bash git clone https://github.com/vgtitov/bsl-ai-toolkit && cd bsl-ai-toolkit bash onboard/onboard.sh # macOS/Linux ``` ```powershell git clone https://github.com/vgtitov/bsl-ai-toolkit ; cd bsl-ai-toolkit .\onboard\onboard.ps1 # Windows ``` The `onboard` script lays out skills, `.mcp.json` profile and rules, sets up env, installs git hooks, and performs self-testing. Next, restart the agent and confirm MCP servers. For a different agent: `sh build.sh <agent>` (Windows — `build.ps1`; see `adapters/README.md`). > **Let the agent configure itself.** You don't have to configure it manually — give the AI agent a ready-made prompt from > [docs/AGENT_SETUP.md](docs/AGENT_SETUP.md), and it will deploy the environment itself (all the user has to do is clone their > 1C sources, enter secrets, and publish the test database). - **Installation of AI Tools (Guide + Traps)** — [docs/AI_INSTALL_GUIDE.md](docs/AI_INSTALL_GUIDE.md). - **Versioning and Updating** — [docs/AI_UPDATE.md](docs/AI_UPDATE.md) (the core is pinned with a semver tag; AI updates itself). - **Environment Health** — `python scripts/doctor.py` (prerequisites + MCP from `.mcp.json` + accesses). ## Adaptation to Your Organization Localization is **configs and a separate layer on top**, not editing the core: 1. Project versions (platform, compatibility mode, configuration, libraries) — in `core/skills/1c-dev/references/conventions-template.md`. 2. `config/layers.example.toml` → your file (`ONEC_LAYERS_CONFIG`): layers/contours (what is the base configuration, what are extensions), labels, scope groups, profiles. Without a file — pure auto-discovery. **MCP code does not need to be changed.** 3. `config/contours.example.md` → your file: contour map/databases for `1c-analyst`. 4. `core/mcp/servers.json` → paths to your tools (via env) → `sh build.sh`. The methodology core, standards, and MCP engine remain as is. ## Documentation - [docs/CONCEPT.md](docs/CONCEPT.md) — idea, methodology, work with artifacts (TZT, tech project), connection with courses and real processes. - [docs/METHODOLOGY_MAP.md](docs/METHODOLOGY_MAP.md) — map: approaches from courses (SDD, Memory Bank, Kiro, subagents, Shotgun) → our documents and process. - [docs/TOOLS.md](docs/TOOLS.md) — tool catalog: what is inside, what it does, how to use. - [docs/AGENT_SETUP.md](docs/AGENT_SETUP.md) — how to entrust setup to the AI agent itself (ready-made prompt). - [docs/EDT_SETUP.md](docs/EDT_SETUP.md) — integration with 1C:EDT (optional MCP plugin: live access to the workspace). - [docs/setup-actions-required.md](docs/setup-actions-required.md) — what a person should do (publishing the database, protection flag, platform). - [docs/AI_INSTALL_GUIDE.md](docs/AI_INSTALL_GUIDE.md) · [docs/AI_UPDATE.md](docs/AI_UPDATE.md) — installation and updating. - [docs/example.md](docs/example.md) — example: how AI leads a task from tech project to code transfer. - [docs/data-access-architecture.md](docs/data-access-architecture.md) — access to live database data (level ladder). - [docs/testing-ladder.md](docs/testing-ladder.md) — how to prove behavior (testing ladder). - [docs/ops-tools-catalog.md](docs/ops-tools-catalog.md) · [docs/zabbix-1c-monitoring-guide.md](docs/zabbix-1c-monitoring-guide.md) — operation and monitoring. - [docs/mcp-deploy-and-use.md](docs/mcp-deploy-and-use.md) · [docs/deploy-center.md](docs/deploy-center.md) — common server per team. - [docs/RELEASING.md](docs/RELEASING.md) — how to release versions (versioning, extension assembly, Git LFS decision). ## License and Disclaimers MIT (see `LICENSE`). Independent anonymized product — there are no and should be no organizations' internal data in the repository. Legal disclaimers (1C trademarks, BSP as reference material, project independence) — `NOTICE.md`; third-party components and licenses — `THIRD_PARTY.md`. ## Contributions PR and issues are welcome — both from people and AI agents. See [CONTRIBUTING.md](CONTRIBUTING.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), [SECURITY.md](SECURITY.md). Read `AGENTS.md` before editing: edit `core/`, add a test for each check, facts — by code/1C documentation.