Content
# 1C AI Development Environment
> **Universal development environment for 1C with AI assistant**: parsing and analysis of 1C metadata from XML dumps, 7 MCP tools for IDE/LLM, 11 BSL code analyzers (150+ rules), JSON DSL → XML compilers (5 types of objects), working with CFE extensions, metadata dependency graph, SKD tracing, generation of handlers/reports/templates/roles, **creating external handlers .epf from scratch without 1C**, SARIF for GitHub Code Scanning.
**Languages:** [English](README.en.md)
[](CHANGELOG.md)
[](ROADMAP.md#transition-criteria)
[](LICENSE)
[](https://www.python.org/)
[](https://openjdk.org/)
[](#tests)
[](#connecting-to-ide--llm-via-mcp)
[](#cli-commands)
---
## 🤖 AI Agents: Read AGENTS.md
**If you are an AI agent (Codex, Cursor, Claude) — start with [`AGENTS.md`](AGENTS.md).**
AGENTS.md — a compact set of rules (170 lines) that you need to know before each work session. The rules were born from real incidents, not theoretical discussions. Contains:
- **Agent workflow** (4 stages: rules → graph → documentation → code)
- **Infrastructure rules** (BSL LS, v8unpack, mobile app)
- **Process rules** (before building EPF, after changes, critical files)
- **Architectural rules** (DRY, locality, BSL module structure)
- **Technical rules** (handler names, list form, queries, commits)
- **Anti-patterns** (8 points "NOT to do")
- **Incident history** (5 incidents → 5 rules)
Extended description: [`docs/AGENTS_MD.md`](docs/AGENTS_MD.md).
---
## What's Inside
### BSL Code Analysis (11 Analyzers, 150+ Rules)
| Component | Rules | What checks |
|-----------|--------|---------------|
| **security_auditor** | 15 | SQL injections, Execute(), hardcoded passwords, COM, RLS, path traversal |
| **check_1c_standards** | 56 | Code style, names, line length, queries, client-server |
| **transaction_checker** | 6 | Unbalanced transactions, without Try/Catch, interactive |
| **query_analyzer** | 10 | SELECT \*, LIKE %, functions in WHERE, JOIN without ON |
| **code_metrics** | 10 | LOC, cyclomatic/cognitive complexity, God Object, health score |
| **architecture_analyzer** | 12 | Dependency cycles, dead code, layering, regions |
| **form_quality_checker** | 9 | Empty/overloaded forms, buttons without commands |
| **skd_quality_checker** | 9 | SKD without parameters, empty queries, overload |
| **check_metadata_standards** | 18 | 1C metadata XML |
| **code_validator** | — | BSL/XML syntax, structure, areas |
| **BSL Language Server** | 187 | External Java analyzer (v1.0.1) |
### 1C Metadata Parsing
| Component | What does |
|-----------|------------|
| **metadata_extractor** | Unified parser of 35 types of objects from XML dump |
| **api-reference** | BSL modules with export methods |
| **skd_parser** | Parsing SKD schemes + trace mode (field tracing) |
| **form_analyzer** | Full form analysis: elements, DataPath, events |
| **cf_extractor** | Own parser .cf without v8unpack |
| **call_graph** | BSL method call graph |
| **dependency_graph** | Metadata dependency graph (networkx) |
### Code Generation (JSON DSL → XML)
| Compiler | What generates | Objects |
|------------|----------------|----------|
| **MetaCompiler** | 1C metadata | 23 types (Catalog, Document, Enum, etc.) |
| **FormCompiler** | Managed forms (Form.xml) | — |
| **SkdCompiler** | SKD schemes (DataCompositionSchema) | — |
| **MxlCompiler** | MXL layouts (printable forms) | — |
| **RoleCompiler** | 1C roles (Rights.xml) | — |
### Working with Extensions (CFE)
| Operation | What does |
|----------|------------|
| **cfe_borrow** | Borrowing an object (ObjectBelonging=Adopted) |
| **cfe_patch_method** | Generating &Before/&After/&ChangeAndControl |
| **cfe_diff** | Extension analysis: what is borrowed, what is intercepted |
### Infrastructure and Tools
| Component | What gives |
|-----------|----------|
| **SARIF reporter** | SARIF 2.1.0 — annotations in GitHub Code Scanning |
| **OpenSpec manager** | Specification-Driven Development (proposal/tasks/design) |
| **Session manager** | Saving/restoring AI sessions |
| **DslCompiler** | Unified facade for 5 compilers |
| **TaskProcessor** | Unified pipeline for CLI and MCP (7 sources + 7 analyzers) |
| **ConfigManager** | Validation of sources + freshness check of indexes |
| **DataPackage** | Data persistence through GitHub Releases |
| **EpfFactory** | Creating .epf from scratch without 1C (templates v8unpack + BSL LS + round-trip) |
| **img_grid** | Grid on screenshot of printable forms for LLM |
| **BM25 + trigrams** | Semantic search by 1C platform methods |
---
## Stability Matrix
> Stage 4.2: explicit stability marking of each subsystem.
> The project is in **Beta** status (see [ROADMAP.md](ROADMAP.md#transition-criteria)).
| Subsystem | Stability | Description |
|------------|--------------|----------|
| **MCP server** (10 tools) | ✅ Stable | Main functionality, 1598 tests |
| **CLI** (19 commands) | ✅ Stable | All commands work, tests pass |
| **BSL analyzers** (11 pcs, 150+ rules) | ✅ Stable | 62 rules in 5 modules (Stage 2.1) |
| **DSL compilers** (5 types) | ✅ Stable | meta, form, skd, mxl, role |
| **CFE manager** (borrow/patch/diff) | ✅ Stable | Decomposed in Stage 2.5 |
| **Config manager** (add/build/validate) | ✅ Stable | Main workflow |
| **Metadata extractor** (35 types) | ✅ Stable | Moved to services.metadata (Stage 2.3) |
| **Search** (BM25 + vector) | ✅ Stable | Hybrid search with fallback |
| **Dependency graph** (networkx) | ✅ Stable | Metadata dependency graph |
| **EpfFactory** (creating .epf) | ⚠️ Beta | Decomposed (Stage 2.2), but v8unpack workaround (ADR-0007) |
| **SARIF reporter** | ⚠️ Beta | Works, but requires tests on real CI |
| **OpenSpec manager** | ⚠️ Beta | SDD workflow, minimal usage |
| **Session manager** | ⚠️ Beta | Saving/restoring sessions |
| **EDT parser** | 🔬 Experimental | MVP (P2.1), 2 TODO (owners, register_records) |
| **RAG with Ollama** | 🔬 Experimental | Optional feature, requires Ollama |
| **Prometheus metrics** | 🔬 Experimental | Optional, NoOp fallback |
| **SaaS/Enterprise/Plugin** | ❄️ Frozen | Moved to `experimental/` (ADR-0006) |
**Legend:**
- ✅ **Stable** — main functionality, tests pass, API is stable
- ⚠️ **Beta** — works, but API or behavior may change
- 🔬 **Experimental** — MVP, may not work in edge cases
- ❄️ **Frozen** — frozen, not supported (see ADR-0006)
---
## Quick Start
### Installation
```bash
# 1. Clone
git clone https://github.com/Pradushkoai/1c-ai-dev-env.git
cd 1c-ai-dev-env
# 2. Install Python package
pip install -e ".[dev,mcp]"
# 3. Install BSL LS (optional, for analyze_bsl)
bash install.sh
# 4. Check environment
1c-ai validate
```
### Installation via Docker
```bash
# Build image (multi-stage, ~5 minutes first time)
docker compose build cli
# Check environment
docker compose run --rm cli validate
# Run MCP server for Cursor / Claude Desktop
docker compose up mcp-server
# Run tests
docker compose run --rm tests
# Get coverage report
docker compose run --rm coverage
# Run linters
docker compose run --rm lint
```
### Add 1C Configuration
```bash
# From ZIP dump of Configurator
1c-ai config add --name ut11 --zip ut11.zip --title "UT 11"
1c-ai config build --name ut11
# → Unpacks to data/configs/ut11/
# → Builds 5 indexes:
# - unified-metadata-index.json (35 types of objects)
# - api-reference.json (BSL modules + methods)
# - skd-index.json (SKD schemes)
# - form-index.json (forms + elements)
# - dependency-graph.json (dependency graph)
```
### Checking Index Freshness
```bash
# Check if indexes are outdated (mtime source vs index)
1c-ai config build --name ut11 --check-freshness
# Check source validity
1c-ai config build --name ut11 --validate
# Forced rebuild
1c-ai config build --name ut11 --force
```
---
## CLI Commands
### Configuration Management
```bash
1c-ai config list # list configurations
1c-ai config add --name X --zip X.zip # add from ZIP
1c-ai config build --name X # build indexes
1c-ai config build --name X --force # forced rebuild
1c-ai config build --name X --check-freshness # check freshness
1c-ai config build --name X --validate # validate sources
```
### BSL Code Analysis
```bash
1c-ai standards module.bsl # 62 1C standard rules
1c-ai bsl analyze module.bsl # BSL LS (187 diagnostics)
1c-ai bsl baseline module.bsl # save baseline
1c-ai bsl diff module.bsl # new errors only
1c-ai solve check module.bsl --level full # all 7 analyzers
1c-ai solve check module.bsl --sarif out.sarif # SARIF for GitHub
```
### Search
```bash
1c-ai search "find element by code" # BM25 by platform methods
1c-ai search-code "create order" --config ut11 # BM25 by config code
1c-ai call-graph --config ut11 --action stats # method call graph
```
### Metadata Dependency Graph
```bash
1c-ai depgraph build --name ut11 # build graph
1c-ai depgraph query --name ut11 \
--query-type what_depends_on \
--object "Catalog.Counterparties" # who depends on object
1c-ai depgraph query --name ut11 --query-type find_cycles # cycles
1c-ai depgraph query --name ut11 --query-type find_unused_objects # dead code
1c-ai depgraph validate --name ut11 # validate graph as DAG
```
### JSON DSL → XML Compilers
```bash
1c-ai dsl meta --json-file catalog.json --output-dir /path/to/config
1c-ai dsl form --json-file form.json --output-path Form.xml
1c-ai dsl skd --json-file skd.json --output-path Template.xml
1c-ai dsl mxl --json-file mxl.json --output-path Template.xml
1c-ai dsl role --json-file role.json --output-dir /path/to/Roles
```
### Working with Extensions (CFE)
```bash
1c-ai cfe borrow --extension-path /ext --config-path /cfg \
--object-ref "Catalog.Counterparties"
1c-ai cfe patch --extension-path /ext \
--module-path "Catalog.Counterparties.ObjectModule" \
--method-name OnWrite --interceptor-type Before
1c-ai cfe diff --extension-path /ext --config-path /cfg
```
### SKD Analysis
```bash
1c-ai skd-trace Template.xml Amount # field tracing through entire chain
1c-ai inspect skd Template.xml --mode trace --name Amount
```
### Unified Inspect (1C Object Analysis)
```bash
1c-ai inspect cf /path/to/Configuration.xml # configuration overview
1c-ai inspect meta /path/to/Catalog.xml # metadata object
1c-ai inspect form /path/to/Form.xml # form
1c-ai inspect skd /path/to/Template.xml # SKD
1c-ai inspect mxl /path/to/Template.xml # MXL layout
1c-ai inspect role /path/to/Rights.xml # role
1c-ai inspect subsystem /path/to/Subsystem.xml # subsystem
1c-ai inspect depgraph /path --name ut11 # dependency graph
```
### OpenSpec (Change Management)
```bash
1c-ai openspec init # initialize
1c-ai openspec proposal --change-id add-feature \
--title "Add Feature" --tasks "T1,T2,T3"
1c-ai openspec list # list changes
1c-ai openspec update --change-id add-feature --task-index 0 --completed
1c-ai openspec archive --change-id add-feature # archive
1c-ai openspec validate --change-id add-feature # validation
```
### Session Management
```bash
1c-ai session save --task "CFE Implementation" \
--completed "borrow,patch" --pending "diff"
1c-ai session restore # restore
1c-ai session retro # retrospective
1c-ai session clear # clear
```
### Data Persistence
```bash
1c-ai data save-pkg --output data-package.zip # save
1c-ai data load-pkg data-package.zip # restore
1c-ai data autosave # autosave
1c-ai data autoload # autorestore
1c-ai data release-push # upload to GitHub Releases
1c-ai data release-pull # download from GitHub Releases
```
### Creating External Processing (.epf)
```bash
1c-ai epf-factory create \
--name "MyProcessing" \
--synonym "My Processing" \
--bsl module.bsl \
--output MyProcessing.epf # EPF from scratch, without 1C
1c-ai epf-factory templates # list templates
```
> Full cycle: templates v8unpack → UUID substitution → BSL code → verification via BSL LS → build → round-trip. No 1C installation required. [Details →](docs/EPF_FACTORY.md)
---
## Connecting to IDE / LLM via MCP
The project includes its own MCP server with 10 tools for Cursor / Claude Desktop / VS Code / JetBrains.
### Setup
**Cursor / Claude Desktop** — add to `mcp.json`:
```json
{
"mcpServers": {
"1c-ai": {
"command": "1c-ai-mcp",
"args": []
}
}
}
```
**VS Code / JetBrains** — via stdio:
```bash
1c-ai mcp serve
```
### MCP Tools Categories
| Category | Tools | Purpose |
|-----------|-------|----------|
| **Configurations** | list_configs, data_status | Configuration Management |
| **Search** | search_1c_methods, search_code | BM25 search by platform and code |
| **BSF Analysis** | analyze_bsl, check_standards, audit_security, check_transactions, analyze_queries, get_code_metrics, analyze_architecture | 11 analyzers |
| **Metadata** | get_object_structure, get_skd_schema, get_form_structure, get_form_elements, get_api_reference, call_graph | Parsing and structure |
| **Quality** | check_form_quality, check_skd_quality, diff_configs | Quality check |
| **Generation** | generate_processing, generate_report, build_epf, validate_generated | Code generation |
| **Context** | solve_context, solve_check | TaskProcessor (7 sources + 7 analyzers) |
| **Knowledge Base** | get_knowledge | Patterns, antipatterns |
| **DSL Compilers** | dsl_compile_meta, dsl_compile_form, dsl_compile_skd, dsl_compile_mxl, dsl_compile_role | JSON → XML |
| **CFE** | cfe_borrow, cfe_patch_method, cfe_diff | Extensions |
| **SKD** | skd_trace | Field tracing |
| **Dependency Graph** | build_dependency_graph, dependency_query | networkx graph |
| **OpenSpec** | openspec_proposal, openspec_list, openspec_update_task, openspec_archive | SDD |
| **Inspect** | inspect | Unified object analysis |
---
## Architecture
```
data/ ← initial XML dumps from Configurator
derived/ ← indexes (metadata, api, skd, form, depgraph)
knowledge_base/ ← patterns, antipatterns, best practices
templates/ ← BSL/XML templates
runtime/ ← state (config-registry, session-state)
docs/1c-xml-specs/ ← 19 XML format specifications for 1C (16K lines)
openspec/ ← Specification-Driven Development
```
### OOP Layer (src/)
```
src/
├── models/ Configuration as data
│ ├── configuration.py Configuration dataclass
│ ├── config_registry.py ConfigurationRegistry
│ └── task.py TaskContext + CheckResult + Violation
├── services/ Business logic
│ ├── path_manager.py PathManager (4-layer architecture)
│ ├── config_manager.py add/build/validate/freshness
│ ├── task_processor.py Unified CLI/MCP pipeline
│ ├── dsl_compiler.py 5 compilers JSON → XML
│ ├── cfe_manager.py Work with CFE extensions (Stage 2.5)
│ ├── diff.py Configuration comparison (Stage 1.2-g3)
│ ├── dependency_graph.py Dependency graph (networkx)
│ ├── openspec_manager.py SDD change management
│ ├── session_manager.py AI session management
│ ├── sarif_reporter.py SARIF 2.1.0 for GitHub Code Scanning
│ ├── bsl_analyzer.py BSL LS wrapper + baseline/diff
│ ├── call_graph.py BSL method call graph
│ ├── search_bm25.py BM25 + trigrams + stemmer
│ ├── search_code.py BM25 by configuration methods
│ ├── knowledge_base.py Knowledge base
│ ├── data_package.py Persistence (autosave/autoload)
│ ├── github_releases.py Push/pull via GitHub REST API
│ ├── backup_manager.py Backup/restore
│ ├── logger.py Structlog (structured logging)
│ ├── analyzers/ BSL analyzers (Stage 1.2-g1)
│ │ ├── __init__.py Analyzer Protocol + Adapters + _load_script
│ │ ├── standards/ 62 rules in 5 modules (Stage 2.1)
│ │ │ ├── style.py 10 style rules
│ │ │ ├── architecture.py 12 architecture rules
│ │ │ ├── queries.py 7 query rules
│ │ │ ├── client_server.py 13 client-server rules
│ │ │ └── misc.py 14 miscellaneous rules
│ │ ├── security_auditor.py 15 security rules
│ │ ├── code_metrics.py 10 code metrics
│ │ ├── transaction_checker.py 6 transaction rules
│ │ ├── query_analyzer.py 10 query rules
│ │ ├── architecture_analyzer.py 12 architecture rules
│ │ ├── form_quality_checker.py 9 form rules
│ │ ├── skd_quality_checker.py 9 SKD rules
│ │ └── check_metadata_standards.py 18 metadata standards rules
│ ├── epf/ EpfFactory utilities (Stage 2.2)
│ │ ├── result.py EpfFactoryResult dataclass
│ │ ├── json_patcher.py JSON v8unpack patches
│ │ ├── bsl_validator.py BSL LS validation
│ │ └── round_trip.py Round-trip check
│ ├── epf_factory.py .epf creation (facade, Stage 2.2)
│ ├── code_generator.py Code generation (Stage 1.2-g2)
│ ├── code_validator.py BSL/XML validation (Stage 1.2-g2)
│ ├── epf_builder.py .epf packager (Stage 1.2-g2)
│ ├── metadata/ 1C metadata parsing (Stage 2.3)
│ │ └── extractor.py 35 object types
│ ├── builders/ Index building (Stage 2.4)
│ │ └── config_index.py unified-metadata-index
│ ├── cfe/ CFE utilities (Stage 2.5)
│ │ ├── result.py BorrowResult, PatchMethodResult, CfeDiffResult
│ │ └── cli.py CLI helpers
│ └── cf/ CF parser (Stage 1.2-g7)
│ └── extractor.py .cf container parser
├── mcp_server.py MCP server (10 tools)
├── mcpserver/ MCP handlers (Stage 1.2)
│ ├── handlers/ 8 handler groups
│ └── tools/ Tool definitions
├── cli_commands/ CLI commands (Stage 1.2)
├── project.py Project orchestrator
├── cli.py Unified CLI (19 commands)
└── exceptions.py Custom exceptions
```
> **Stages 1-2**: 14 scripts moved from `scripts/` to `src/services/`,
> 5 god files decomposed. See [docs/AUDIT_SCRIPTS_SERVICES.md](docs/AUDIT_SCRIPTS_SERVICES.md).
---
## Testing
```bash
# All tests
python -m pytest tests/ -v
# Key tests only (fast)
python -m pytest tests/test_dsl_compiler.py tests/test_cfe_manager.py \
tests/test_dependency_graph.py tests/test_openspec_manager.py \
tests/test_session_manager.py tests/test_skd_trace.py -v
# With coverage
python -m pytest tests/ --cov=src --cov-report=term-missing --cov-fail-under=30
# Property-based tests (hypothesis)
python -m pytest tests/test_property.py -v --hypothesis-show-statistics
# Benchmarks
python -m pytest tests/test_benchmarks_synthetic.py --benchmark-only -v
# Pre-commit hooks
pre-commit install
pre-commit run --all-files
```
### Test Statistics
| Metric | Value |
|---------|--------|
| Test files | 100 |
| Test functions | 1595 (unit + integration + e2e + snapshot) |
| Property-based tests | 13 (hypothesis, ~1300 cases) |
| Synthetic benchmarks | 19 |
| Coverage gate | 70% (target: 85%, actual: 71.4%) |
| Pre-commit hooks | ruff + mypy + pytest |
---
## CI/CD
| Workflow | What it does |
|----------|--------------|
| `ci.yml` — lint | ruff check + format + mypy |
| `ci.yml` — version-check | Version consistency check |
| `ci.yml` — test | pytest (unit + integration + e2e + benchmarks) |
| `ci.yml` — coverage | pytest --cov=src --cov-fail-under=30 |
| `ci.yml` — benchmark | Synthetic benchmarks + comparison with baseline |
| `code-scanning.yml` | SARIF → GitHub Code Scanning (annotations in PR) |
---
## Documentation
| Section | Where |
|--------|------|
| 1C XML specifications | `docs/1c-xml-specs/` — 19 files, 16K lines |
| Architecture | `docs/ARCHITECTURE.md` |
| API | `docs/API.md` |
| MCP integration | `docs/MCP_INTEGRATION.md` |
| Troubleshooting | `docs/TROUBLESHOOTING.md` |
| Knowledge base | `knowledge_base/` — patterns, anti-patterns, best practices |
| Change history | `CHANGELOG.md` |
---
## Technologies
| Component | Technology |
|-----------|------------|
| Primary language | Python 3.10+ |
| BSL Language Server | Java 17+ (v1.0.1, 187 diagnostics) |
| MCP SDK | Python mcp |
| Dependency graph | networkx |
| Structured logging | structlog |
| Linting | ruff + mypy |
| Testing | pytest + hypothesis + pytest-benchmark |
| Containerization | Docker (multi-stage) + docker-compose |
| CI/CD | GitHub Actions (5 jobs + SARIF) |
---
## License
MIT — see [LICENSE](LICENSE)
---
## Acknowledgements
- [1c-ai-development-kit](https://github.com/Arman-Kudaibergenov/1c-ai-development-kit) — for JSON DSL specifications and 1C XML format documentation
- [BSL Language Server](https://github.com/1c-syntax/bsl-language-server) — for BSL static analysis
- [MCP SDK](https://github.com/modelcontextprotocol/python-sdk) — for Model Context Protocol
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available