Content
MCP-1C
**MCP Server for 1C:Enterprise platform** — metadata analysis, code generation, and integration with Claude.
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
## Capabilities
- **Metadata Engine** — parsing and indexing of 1C configuration metadata
- **Code Engine** — analysis of code in BSL language (1C built-in language)
- **Template Engine** — code generation from templates
- **MXL Engine** — parsing of tabular document layouts
- **Platform Knowledge Base** — knowledge base of 8.3.24 platform API
- **BSL Language Server** — integration with BSL LS for validation and formatting
- **Skills & Agents** — ready-made scenarios for Claude Code
## Installation
### From PyPI (recommended)
```bash
pip install mcp-1c
```
### From sources
```bash
git clone https://github.com/your-org/mcp-1c.git
cd mcp-1c
pip install -e ".[dev]"
```
## Quick Start
### 1. MCP Server Configuration
#### Global configuration (for Claude Desktop)
Add to `~/.claude/mcp_servers.json` (Linux/Mac) or `%USERPROFILE%\.claude\mcp_servers.json` (Windows):
```json
{
"mcpServers": {
"mcp-1c": {
"command": "mcp-1c",
"args": []
}
}
}
```
#### Local configuration (for a specific 1C configuration)
Create a `.mcp.json` file in the root of the extracted configuration:
```json
{
"mcpServers": {
"mcp-1c": {
"command": "python",
"args": ["-m", "mcp_1c"]
}
}
}
```
> **Note:** Local configuration is convenient for working with multiple configurations — each uses its own cache.
### 2. Initialization
In Claude Code, execute:
```
Initialize configuration at path C:\Projects\MyConfig
```
Or use the skill:
```
/1c-metadata Catalog.Nomenclature
```
## Work Pipeline
### How Indexing Works
```
┌─────────────────────────────────────────────────────────────────────┐
│ 1. INITIALIZATION │
├─────────────────────────────────────────────────────────────────────┤
│ metadata.init(config_path) │
│ │ │
│ ▼ │
│ Configuration.xml ──► Parsing object list │
│ │ (Catalogs, Documents, Registers...) │
│ │ │
│ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Catalog/ │ │ Document/ │ │ Register/ │ ... │
│ │ Object.xml │ │ Object.xml │ │ Object.xml │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ └──────────────────┼──────────────────┘ │
│ │ │
│ ▼ │
│ Parallel parsing (4 threads) │
│ │ │
│ ▼ │
│ ┌─────────────────────────┐ │
│ │ .mcp_1c_cache.db │ ◄── SQLite database │
│ │ (in configuration folder)│ with WAL mode │
│ └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ 2. USING CACHE │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ metadata.get("Catalog", "Nomenclature") │
│ │ │
│ ▼ │
│ ┌─────────────────┐ HIT ┌─────────────────┐ │
│ │ LRU In-Memory │ ───────────► │ Return data │ │
│ │ Cache │ └─────────────────┘ │
│ └────────┬────────┘ │
│ │ MISS │
│ ▼ │
│ ┌─────────────────┐ HIT ┌─────────────────┐ │
│ │ SQLite Cache │ ───────────► │ Return data │ │
│ │ (MD5 check) │ │ + update LRU │ │
│ └────────┬────────┘ │ cache │ │
│ │ MISS/STALE └─────────────────┘ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ XML file parsing│ ───────────► │ Save to both │ │
│ │ │ │ caches │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ 3. INCREMENTAL UPDATE │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ File Watcher (watchfiles) │
│ │ │
│ ▼ │
│ Change in .xml or .bsl file │
│ │ │
│ ▼ │
│ Debounce (500ms) ──► Extract type/name from path │
│ │ │
│ ▼ │
│ Re-parsing of only changed object │
│ │ │
│ ▼ │
│ Update record in SQLite + invalidate LRU cache │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
### Database Structure
The `.mcp_1c_cache.db` database is created **in the configuration folder** and contains:
| Table | Description |
|---------|----------|
| `metadata_objects` | Basic object data (name, type, synonym, UUID) |
| `attributes` | Object attributes |
| `tabular_sections` | Tabular sections |
| `modules` | Paths to modules (.bsl files) |
| `subsystems` | Subsystems and their contents |
### Supported Dump Formats
| Format | Source | Support |
|--------|----------|-----------|
| XML Configurator | Configurator → Dump configuration to files | ✅ Full |
| EDT Project | 1C:EDT → Export | ✅ Full |
> Format is determined automatically by the structure of `Configuration.xml`
## Tools
### Metadata Tools
| Tool | Description |
|------------|----------|
| `metadata.init` | Initialize metadata index |
| `metadata.list` | List objects by type |
| `metadata.get` | Full object information |
| `metadata.search` | Search by name/synonym |
| `metadata.tree` | Subsystem tree |
| `metadata.attributes` | Object attributes |
| `metadata.forms` | Object forms |
| `metadata.templates` | Object layouts |
| `metadata.registers` | Document registers |
| `metadata.references` | Object links |
### Code Tools
| Tool | Description |
|------------|----------|
| `code.module` | Get module code |
| `code.procedure` | Get procedure code |
| `code.resolve` | Find definition |
| `code.usages` | Find usages |
| `code.dependencies` | Dependency graph |
| `code.analyze` | Extended module analysis |
| `code.callgraph` | Procedure call graph |
| `code.validate` | Syntax check |
| `code.lint` | Static analysis |
| `code.format` | Code formatting |
| `code.complexity` | Complexity analysis |
### Generate Tools
| Tool | Description |
|------------|----------|
| `generate.query` | Query Generation |
| `generate.handler` | Event Handler Generation |
| `generate.print` | Print Form Generation |
| `generate.movement` | Movement Generation by Registers |
| `generate.api` | API Method Generation |
| `generate.form_handler` | Form Handlers |
| `generate.subscription` | Event Subscription |
| `generate.scheduled_job` | Scheduled Job |
### Query Tools
| Tool | Description |
|------------|----------|
| `query.parse` | Query Parsing |
| `query.validate` | Validation with Metadata |
| `query.optimize` | Query Optimization |
| `query.explain` | Query Explanation |
| `query.tables` | Tables in Query |
### Pattern Tools
| Tool | Description |
|------------|----------|
| `pattern.list` | Pattern List |
| `pattern.get` | Get Pattern |
| `pattern.apply` | Apply Pattern |
| `pattern.suggest` | Suggest Pattern |
| `pattern.search` | Pattern Search |
### Template Tools (MXL)
| Tool | Description |
|------------|----------|
| `template.get` | Layout Structure |
| `template.parameters` | Layout Parameters |
| `template.areas` | Layout Areas |
| `template.generate_fill_code` | Layout Fill Code Generation |
| `template.find` | Layout Search |
### Platform Tools
| Tool | Description |
|------------|----------|
| `platform.method` | Platform Method Description |
| `platform.type` | Data Type Description |
| `platform.event` | Object Event Description |
| `platform.search` | Platform API Search |
| `platform.global_context` | Global Context |
### Config Tools
| Tool | Description |
|------------|----------|
| `config.options` | Functional Options |
| `config.constants` | Constants |
| `config.scheduled_jobs` | Scheduled Jobs |
| `config.event_subscriptions` | Event Subscriptions |
| `config.exchanges` | Exchange Plans |
| `config.http_services` | HTTP Services |
## Skills & Agents
### Architecture
Skills and Agents are implemented as MCP Prompts — predefined scenarios that guide Claude through a sequence of actions using server tools.
```
┌─────────────────────────────────────────────────────────────────────┐
│ PROMPTS ARCHITECTURE │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ BasePrompt (base.py) │
│ │ │
│ ├── Skills (skills.py) ─── Simple one-step tasks │
│ │ └── /1c-query, /1c-metadata, /1c-handler... │
│ │ │
│ ├── Agents (agents.py) ─── Complex multi-step workflows │
│ │ └── /1c-explore, /1c-implement, /1c-debug... │
│ │ │
│ └── PromptRegistry (registry.py) ─── Registration and invocation│
│ │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ HOW IT WORKS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ User ──► /1c-query object="Справочник.Номенклатура" │
│ │ │
│ ▼ │
│ PromptRegistry.get_prompt_messages("1c-query", arguments) │
│ │ │
│ ▼ │
│ QuerySkill.generate_messages(arguments) │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Prompt with instructions for Claude: │ │
│ │ 1. Use metadata.get to get information │ │
│ │ 2. Use metadata.attributes for attributes │ │
│ │ 3. Use generate.query for query generation │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Claude performs instructions, calling MCP Tools │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
### Skills — simple tasks
Skills solve specific tasks in a few steps. Called via `/` commands.
| Skill | Description | Arguments |
|-------|----------|-----------|
| `/1c-query` | Query generation for data | `object` (required), `fields`, `conditions` |
| `/1c-metadata` | Metadata information | `object` (required) |
| `/1c-handler` | Event handler generation | `object`, `event` (required), `description` |
| `/1c-print` | Print form generation | `object` (required), `template`, `description` |
| `/1c-usages` | Code usage search | `name` (required), `scope` |
| `/1c-validate` | Code syntax check | `module` (required) |
| `/1c-deps` | Module dependency graph | `module` (required), `depth` |
| `/1c-movement` | Movement generation by registers | `document` (required), `register` |
| `/1c-format` | Code formatting | `module` (required) |
| `/1c-explain` | Code explanation | `module` (required), `procedure` |
### Examples of using Skills
```
# Query generation with conditions
/1c-query object="Справочник.Номенклатура" fields="Код,Наименование" conditions="Родитель = &Группа"
# Full object information
/1c-metadata object="Документ.РеализацияТоваров"
# Event handler generation
/1c-handler object="Документ.ПоступлениеТоваров" event="ПередЗаписью" description="Checking warehouse fill level"
# Print form generation
/1c-print object="Документ.Счет" description="Print form with product table and totals"
# Procedure usage search
/1c-usages name="ПолучитьЦену" scope="all"
# Document movement generation
/1c-movement document="РеализацияТоваров" register="РегистрНакопления.ОстаткиТоваров"
# Dependency analysis
/1c-deps module="Документ.РеализацияТоваров.МодульОбъекта" depth="3"
# Specific procedure explanation
/1c-explain module="ОбщийМодуль.РаботаСТоварами" procedure="РассчитатьЦену"
```
### Agents — complex multi-step tasks
Agents are advanced scenarios for complex tasks. They contain a detailed plan of actions with many steps.
| Agent | Description | Arguments |
|-------|----------|-----------|
| `/1c-explore` | Configuration exploration | `path` (required), `focus`, `depth` |
| `/1c-implement` | Functionality implementation | `task` (required), `object`, `style` |
| `/1c-debug` | Debugging and diagnostics | `problem` (required), `module`, `error` |
| `/1c-configure` | Typical configuration setup | `goal` (required), `configuration`, `approach` |
### Examples of using Agents
```
# Configuration exploration
/1c-explore path="C:\Projects\MyConfig" focus="documents" depth="detailed"
# New functionality implementation
/1c-implement task="Add automatic discount calculation when conducting a document" object="Документ.РеализацияТоваров" style="bsp"
# Problem debugging
/1c-debug problem="Document does not conduct according to the remainder register" module="Документ.РеализацияТоваров.МодульОбъекта" error="Insufficient stock on warehouse"
# Typical configuration setup
/1c-configure goal="Add a new price type and configure its calculation" configuration="УТ" approach="extension"
```
### Difference between Skills and Agents
| Characteristic | Skills | Agents |
|----------------|--------|--------|
| Complexity | Simple tasks | Complex tasks |
| Number of steps | 3-5 steps | 10-20+ steps |
| Scope of application | Specific operation | Full workflow |
| Example | Generate query | Explore entire configuration |
### Creating custom Skills/Agents
Skills and Agents are defined in `src/mcp_1c/prompts/`. To create a new one:
```python
# Example of creating a custom Skill
class CustomSkill:
def __init__(self, arguments):
self.arguments = arguments
def generate_messages(self):
# Logic for generating messages for Claude
pass
```
# src/mcp_1c/prompts/skills.py
class MyCustomSkill(BasePrompt):
name: ClassVar[str] = "1c-my-skill"
description: ClassVar[str] = "Description of my skill"
arguments: ClassVar[list[PromptArgument]] = [
PromptArgument(
name="param",
description="Parameter description",
required=True,
),
]
async def generate_messages(
self, arguments: dict[str, str]
) -> list[PromptMessage]:
param = arguments.get("param", "")
prompt = f"""Perform a task with the parameter: {param}
Steps:
1. Use metadata.get for ...
2. Use code.analyze for ...
3. Form the result
"""
return [self.create_user_message(prompt)]
```
Then register in `PromptRegistry._register_all_prompts()`.
## Examples of usage
### Metadata analysis
```python
# Get information about a catalog
metadata.get type="Catalog" name="Products"
# Find all documents with "Sale" in the name
metadata.search query="Sale" type="Document"
# Get document attributes
metadata.attributes type="Document" name="GoodsRealization"
```
### Code analysis
```python
# Get the code of an object module
code.module type="Document" name="GoodsRealization" module_type="ObjectModule"
# Find all uses of a procedure
code.usages type="CommonModule" name="GeneralPurpose" procedure="GetValue"
# Get the dependency graph
code.dependencies type="Document" name="GoodsRealization"
```
### Code generation
```python
# Generate a query
generate.query template="select_with_filter"
table="Catalog.Products"
filter_field="Parent"
# Generate a handler
generate.handler template="before_write"
object_type="Document"
object_name="GoodsRealization"
# Generate movements
generate.movement template="expense"
register="AccumulationRegister.GoodsRemains"
document="GoodsRealization"
```
## Architecture
```
mcp-1c/
├── src/mcp_1c/
│ ├── __main__.py # Entry point
│ ├── server.py # MCP Server
│ ├── config.py # Configuration
│ │
│ ├── domain/ # Domain models (Pydantic)
│ │ ├── metadata.py # Metadata models
│ │ ├── code.py # Code models
│ │ ├── templates.py # Template models
│ │ ├── mxl.py # MXL models
│ │ └── platform.py # Platform models
│ │
│ ├── engines/ # Processing engines
│ │ ├── metadata/ # Metadata Engine
│ │ ├── code/ # Code Engine
│ │ ├── templates/ # Template Engine
│ │ ├── mxl/ # MXL Engine
│ │ └── platform/ # Platform Engine
│ │
│ ├── tools/ # MCP Tools
│ │ ├── metadata_tools.py
│ │ ├── code_tools.py
│ │ ├── generate_tools.py
│ │ ├── query_tools.py
│ │ ├── pattern_tools.py
│ │ ├── template_tools.py
│ │ ├── platform_tools.py
│ │ └── config_tools.py
│ │
│ ├── prompts/ # Skills & Agents
│ │ ├── skills.py
│ │ └── agents.py
│ │
│ └── utils/ # Utilities
│ ├── logger.py
│ ├── profiler.py
│ └── lru_cache.py
│
└── tests/ # Tests
```
## Optimizations
MCP-1C is optimized for working with large configurations:
- **SQLite WAL mode** — improved write performance
- **In-memory LRU Cache** — caching frequent queries
- **Parallel Indexing** — parallel object indexing
- **Batch Operations** — batch write operations
- **Incremental Updates** — updating only changed files
## Development
### Running tests
```bash
pytest
pytest --cov=mcp_1c
```
### Code checking
```bash
ruff check .
mypy src/mcp_1c
black --check .
```
### Formatting
```bash
ruff check --fix .
black .
```
## Requirements
- Python 3.11+
- MCP SDK 1.0+
- lxml 5.0+
- aiosqlite 0.19+
- watchfiles 0.21+
### Optional
- BSL Language Server — for validating and formatting BSL code
## License
MIT License. See [LICENSE](LICENSE).
## Authors
- MCP-1C Team
## Links
- [MCP Protocol](https://modelcontextprotocol.io/)
- [1C:Enterprise](https://1c.ru/)
- [BSL Language Server](https://github.com/1c-syntax/bsl-language-server)
