# kd-rules-mcp — правила обмена 1С через агента: «Конвертация данных» 2 и 3

MCP-сервер, с которым агент (Claude Code, Cursor и другие MCP-клиенты) читает, собирает, правит и проверяет
правила обмена для 1С. Без Конфигуратора «Конвертации данных» и ручной работы в её базе.

- **«Конвертация данных 2»** — `ПравилаОбмена` формата 2.01, правила регистрации и правила корреспондента по
  структурам метаданных двух конфигураций.
- **«Конвертация данных 3»** (обмен через универсальный формат, EnterpriseData) — модуль менеджера обмена:
  разбор, проверка против схемы формата и конфигурации, доработка типового обмена расширением, собственный
  модуль правил с нуля или импортом типового и перенос правил регистрации с КД 2.

Сервер детерминированный: разбирает выгрузки и правила, предлагает кандидатов сопоставления, пишет результат и
проверяет его. Что во что конвертировать, решает агент — и показывает решения в отчёте и в диффе.

## Возможности

### Общее

| Что | Как |
|---|---|
| **Метаданные конфигураций** | Из XML-выгрузки конфигурации и расширений (по имени проекта из `projects.yaml` или по путям) либо из файла MD83Exp. Данные базы не нужны |

### «Конвертация данных 3» — обмен через универсальный формат

| Что | Как |
|---|---|
| **Разбор модуля менеджера обмена** | Правила обработки данных, конвертации объектов, свойств и предопределённых данных, обработчики, алгоритмы — без исполнения кода 1С. Поиск: какое правило и какой обработчик отвечают за объект или реквизит |
| **Схема формата** | Типы и свойства пакетов XDTO нужной версии формата прямо из выгрузки конфигурации |
| **Проверки** | Связность модуля (обработчики, ветки диспетчера, ссылки правил) и правила против схемы формата и структуры конфигурации |
| **Версии формата** | Какой модуль менеджера обслуживает какую версию формата в каждой из двух конфигураций и где они расходятся |
| **Расширения** | Что расширения конфигурации меняют в обмене: свои модули менеджера, перехваты, добавленные правила |
| **Доработка типового обмена** | Добавить реквизит в обмен, не трогая типовую конфигурацию: сервер подбирает кандидатов, собирает расширение с правилом и обработчиками и пишет инструкцию по установке |
| **Собственный модуль правил** | Построить модуль менеджера обмена с нуля или взять типовой за основу, когда типовых правил нет или они не подходят: проект хранится на сервере между сеансами, каждая правка — предпросмотр и применение. Правила объектов и обработки данных, свойства шапки всех видов (прямые, ссылочные, через предопределённые данные, алгоритмические), табличные части, поиск, обработчики, алгоритмы, события конвертации, параметры. Проверки против схемы формата, структуры конфигурации и исполнителя БСП — до сборки; на выходе комплект расширения с инструкцией по установке (объекты вне состава плана обмена комплект добавляет в состав) или перенос руками |
| **Перенос правил КД 2 в КД 3** | Доказано на действующем обмене двух конфигураций: 84 правила перенесены агентом через сервер и проверены живым обменом в обе стороны; порядок и решения — в скилле `kd3-rules` |
| **Перенос регистрации с КД 2** | Правила регистрации действующего обмена на правилах КД 2 переносятся на план универсального формата: имя плана и реквизиты узла заменяются или меняются на другие с другим значением (когда у нового плана смысл даёт иной флаг), отборы и код сохраняются; отбор по пометке удаления добавляется по желанию; недостающий реквизит узла добавляет расширение из комплекта; правило для объекта вне состава плана и всё, что после установки сломало бы запись объектов, видно до сборки |

### «Конвертация данных 2»

| Что | Как |
|---|---|
| **Чтение и запись правил** | Без потерь: импорт → экспорт даёт семантически тот же XML (проверено на 60 реальных макетах правил) |
| **Подсказки сопоставления** | Объекты, реквизиты, значения перечислений — по алгоритму автонастройки КД; «примитив → ссылка» автоматически не сопоставляется |
| **Правка правил** | Создание, изменение и удаление ПКО, ПКС, ПКЗ, ПВД, ПОД, алгоритмов, запросов, параметров. ПКО сразу с реквизитами по подсказкам. Ссылки на несуществующие правила и объекты отклоняются |
| **Правила регистрации** | Сборка из состава плана обмена по ПВД |
| **Обратное направление** | Черновик правил корреспондента зеркалированием; обработчики — списком «перенести вручную» |
| **Проверки** | Формат (как читает БСП), соответствие обеим конфигурациям, ссылки на алгоритмы, параметры обработчика поиска; синтаксис кода обработчиков (внешним синтакс-чекером); штатная загрузка в базу КД; штатная загрузка правил БСП в песочнице без записи в базу |

Все инструменты сервера с параметрами, ответами и кодами ошибок — **[docs/tools.md](docs/tools.md)**. Сокращения
(ПКО, ПКС, ПКЗ, ПВД, ПОД, ПРО, БСП, MD83Exp…) и термины сервера — **[docs/glossary.md](docs/glossary.md)**.

Для агентов в репозитории есть скиллы в `.claude/skills` — их читают Claude Code, Cursor и OpenCode; в папку
проекта 1С их ставит `uv run python scripts/build_packs.py --dest <папка проекта> --client claude`
([установка, шаг 6](docs/INSTALL.md#6-подключить-агента)):
- `kd2-rules-build` — порядок построения ПКО → ПКС → ПВД → ПРО и чек-лист проверок; справочники по видам
  правил (`references/`: ПКО, поиск, ПКС, ПКЗ, ПВД, обработчики, ПРО) — что каждое поле и флаг делает в БСП;
- `kd2-exchange-pitfalls` — «грабли» обменов через БСП: симптом → причина → проверка → исправление,
  с доказательствами по коду БСП (дубли при загрузке, поиск по полям, объекты «только по ссылке»…);
- `kd3-rules` — обмен через универсальный формат (EnterpriseData, правила КД 3): как разобрать модуль менеджера
  обмена, проверить связность и свериться со схемой формата, написать собственный модуль и перенести на него
  правила КД 2 (`references/writer.md`, `registration.md`, `recipes.md`); что БСП делает с правилами — со ссылками
  на её код; грабли живых обменов (`pitfalls.md`);
- `kd-install` — установка и подключение сервера агентом, с вопросами человеку и проверкой после каждого шага.

## С чем работает в паре

Разбор, правка и проверка правил работают без других серверов. Но код обработчиков агент пишет против
конфигураций, и для полного цикла ему нужны MCP-серверы для работы с кодом 1С. Мы используем пакет
**MCP-серверов для 1С от comol** — он подключается через `shared_mcp` и `code_mcp` в `projects.yaml`:

- **Пакет MCP-серверов для 1С** — [vibecoding1c.ru/mcp_server](https://vibecoding1c.ru/mcp_server): граф и поиск
  по коду и метаданным конфигурации, синтакс-чекер BSL (им проверяется код обработчиков после `handlers_export`),
  справка платформы, поиск по БСП, шаблоны кода, ревью кода, UI-тестирование форм (MCP QA).
- **Правила и скиллы для агентов в проектах 1С** — [github.com/comol/ai_rules_1c](https://github.com/comol/ai_rules_1c):
  ставят эти серверы в проект и учат агента ими пользоваться (`.mcp.json` проекта, из которого `setup_local.py`
  берёт адреса).
- **MCP в самой информационной базе** (запросы, фрагменты кода, журнал регистрации на живых данных песочницы) —
  инструменты [github.com/comol/mcp_designer_tools](https://github.com/comol/mcp_designer_tools) для
  «Конструктора MCP-серверов для 1С»; в `projects.yaml` — `data_mcp` у базы-песочницы.

## 1. Установка

Пошагово, с проверкой после каждого шага и разбором ошибок — **[docs/INSTALL.md](docs/INSTALL.md)**. Поручить
установку агенту: «Установи kd-rules-mcp по
https://github.com/egordoronchenko/kd-rules-mcp/blob/main/.claude/skills/kd-install/SKILL.md».
Ниже — коротко, для тех, кто знаком с Docker и MCP.

Для готового образа нужен Docker с Compose. Для сборки из клона — ещё Python 3.12 с
[`uv`](https://docs.astral.sh/uv/); для необязательных финальных проверок — Windows с платформой 1С 8.3
(см. раздел 4). «Конвертация данных» для работы сервера не нужна.

### Быстрый старт (образ)

Выберите выпущенный тег `vX.Y.Z` с образом в [релизах](https://github.com/egordoronchenko/kd-rules-mcp/releases).
В пустую папку скачайте три файла **этого тега**:
[docker-compose.yml](https://raw.githubusercontent.com/egordoronchenko/kd-rules-mcp/vX.Y.Z/docker-compose.yml),
[projects.example.yaml](https://raw.githubusercontent.com/egordoronchenko/kd-rules-mcp/vX.Y.Z/projects.example.yaml),
[projects.local.example.yaml](https://raw.githubusercontent.com/egordoronchenko/kd-rules-mcp/vX.Y.Z/projects.local.example.yaml).
В ссылках и командах замените `X.Y.Z` выбранной версией. Клон, Git и Python/uv не нужны.

Три команды в PowerShell (между первой и второй скопируйте примеры в `projects.yaml` и
`projects.local.yaml`, заполните свои проекты и **абсолютные пути на вашей машине**;
`image_tag: X.Y.Z` закрепит тот же образ для compose):

```powershell
'docker-compose.yml','projects.example.yaml','projects.local.example.yaml' | ForEach-Object { Invoke-WebRequest "https://raw.githubusercontent.com/egordoronchenko/kd-rules-mcp/vX.Y.Z/$_" -OutFile $_ }
docker run --rm -v "${PWD}:/work" ghcr.io/egordoronchenko/kd-rules-mcp:X.Y.Z setup
docker compose up -d
```

Для sh настройка: `docker run --rm --user "$(id -u):$(id -g)" -v "$(pwd):/work" ghcr.io/egordoronchenko/kd-rules-mcp:X.Y.Z setup`.
Для Windows cmd том — `-v "%cd%":/work`.
Без `--user` файлы настройки на Linux принадлежат root, `setup` об этом предупреждает.
`setup` пишет те же настройки, что локальный скрипт ниже; пути проектов в override остаются путями хоста.
Внешние `.mcp.json` и `.dev.env` читаются, если проекты также подключены в контейнер настройки
(пример `--project-mount` — в INSTALL). Папки `rules_dir` и `writable_extensions` создайте заранее.

Скиллы — `kd-rules-mcp-skills-claude-X.Y.Z.zip` (Claude Code, Cursor, OpenCode) или
`kd-rules-mcp-skills-agents-X.Y.Z.zip` (Codex) из того же релиза; установите одну упаковку.
В существующем проекте объедините запись `kd-rules-mcp` из `.mcp.json` с текущей и укажите свой
`server_url` и заголовок при `token`. Из клона можно использовать `scripts/build_packs.py --dest …`.
Точные команды PowerShell и sh, проверка без клона и откат — [INSTALL](docs/INSTALL.md#готовый-образ-без-клона).

### Из исходников

Настройки разделены на файлы (в git — только примеры):

| Файл | Что в нём | В git |
|---|---|---|
| `projects.yaml` (пример — `projects.example.yaml`) | проекты → конфигурации (выгрузка и расширения, пути **от папки проекта**) → базы (роль «песочница»/«боевая», строка соединения); серверы кода проекта; обмены между проектами | нет (в форке команды можно хранить) |
| `projects.local.yaml` (пример — `projects.local.example.yaml`) | где на **этой** машине лежит папка каждого проекта (любые диски), адрес сервера, путь к платформе 1С, логины баз (`logins`) | нет, у каждого свой |
| `.dev.env` проектов 1С | логин базы (`IB_USER`, `IB_PASSWORD`), если у базы в `projects.yaml` задан `dev_env` | нет |

```powershell
git clone https://github.com/egordoronchenko/kd-rules-mcp.git
cd kd-rules-mcp
copy projects.example.yaml projects.yaml                 # описать свои проекты и базы
copy projects.local.example.yaml projects.local.yaml     # указать папки проектов на этой машине
uv sync
uv run python scripts/setup_local.py                     # пишет docker-compose.override.yml и .mcp.json
docker compose up -d --build
```

`setup_local.py` подключает папки проектов к контейнеру **только на чтение** и собирает для агентов `.mcp.json`
(Claude Code) и `.cursor/mcp.json` (Cursor): этот сервер, общие серверы 1С из `shared_mcp`, серверы поиска по коду
каждого проекта с префиксом проекта (`bp-1c-code-metadata-mcp`…) и серверы данных песочниц — адреса берутся из
`.mcp.json` самих проектов. Сервер данных боевой базы агентам не подключается. После правки `projects*.yaml` —
снова `setup_local.py` и `docker compose up -d`.

Контейнер `kd_rules_mcp` (порт 8060) пишет в `workspace\` репозитория и в папки живых правил проектов
(`rules_dir` проекта в `projects.yaml` — их `setup_local.py` подключает **на запись**, остальной проект только на
чтение); загруженные структуры хранит в томе `kd2_structures_cache`. Порт по умолчанию опубликован только на
`127.0.0.1` — сервер виден своей машине. Для команды в `projects.local.yaml` задают `bind` (интерфейс) и
`token`: `setup_local.py` публикует порт на этот интерфейс и включает проверку заголовка
`Authorization: Bearer`; без токена на внешнем интерфейсе настройка отказывается
([архитектура, §8](docs/architecture.md#8-развёртывание-и-безопасность)).

Для доставки в своё расширение у конфигурации добавьте `writable_extensions: [src/cfe/МоёРасширение]`
(путь должен быть в `extensions`): `setup_local.py` подключит эту выгрузку на запись;
`delivery={"mode":"user_extension","extension":"МоёРасширение"}` выбирает её вместо нового расширения.

**Правила прямо в репозитории проекта.** Правила, загруженные в базу из файла, живут вне конфигурации — без
истории и диффа. Заведите в репозитории проекта папку (например, `ПравилаОбмена\`) и укажите её в `rules_dir`:
агент открывает правила оттуда (`rules_open`) и сохраняет туда же (`rules_save` с путём в этой папке), изменение —
обычный коммит проекта. Папки нет на диске — `setup_local.py` предупредит и не подключит её (иначе Docker создал
бы её сам). `project_list` показывает `rules_dir` проекта и можно ли туда писать. Удобная раскладка — по папке
на план обмена с файлами под именами из архива БСП (`ExchangeRules.xml`, `CorrespondentExchangeRules.xml`,
`RegistrationRules.xml`): тогда ZIP для загрузки в базу собирает `rules_pack(folder=…)` — файлы байт в байт,
состав как ждёт БСП, в ответе — какой формой загружать и несогласованность частей.

**Подключение агента.** Claude Code: запустить `claude` в папке репозитория и одобрить серверы из `.mcp.json`
(проверка — `claude mcp list`). Cursor: включить серверы в настройках MCP. Без Docker сервер запускается
`uv run kd-rules-mcp` (streamable HTTP, `/mcp`).

### Переход с kd2-rules-mcp

Проект переименован в `kd-rules-mcp` (пакет `kd_rules_mcp`, контейнер `kd_rules_mcp`, ключ сервера
`kd-rules-mcp`), потому что сервер давно работает и с КД 2, и с универсальным форматом (КД 3). Старый адрес
GitHub перенаправляется. Если сервер уже стоял: `git pull`, затем `uv run python scripts/setup_local.py` —
он перепишет `.mcp.json` и `.cursor/mcp.json` под новый ключ и подскажет, чем остановить прежний контейнер;
`docker compose up -d --build`; в проектах 1С — снова `scripts/build_packs.py --dest <папка> --client claude`:
установщик уберёт папки прежних имён скиллов (`kd2-ed-rules` → `kd3-rules`, `kd2-install` → `kd-install`,
`KD2-RULES.md` → `KD-RULES.md`). Имена инструментов MCP, идентификаторы проверок, коды ошибок и переменные
окружения `KD2_*` не менялись.

## 2. Что нужно на входе

Полная выгрузка базы (данные) **не нужна** — только метаданные конфигураций:

| Вход | Когда | Инструмент |
|---|---|---|
| Проект из `projects.yaml` — XML-выгрузка конфигурации и расширений из его репозитория | исходники в git | `structure_load_project` — по имени проекта |
| Произвольная XML-выгрузка по путям | разовая, вне проектов | `structure_load_xml` |
| Файл обработки MD83Exp («Выгрузка структуры метаданных» из поставки КД) | исходников нет | `structure_load_md83exp` |

Код модулей для обработчиков агент смотрит через серверы кода проектов (или в той же XML-выгрузке):
выгрузочные обработчики — против конфигурации-источника, загрузочные — против приёмника. В MD83Exp кода нет.

**Если выгрузка изменилась.** Сервер замечает изменение при повторной загрузке — по `Configuration.xml` и
`ConfigDumpInfo.xml`, которые Конфигуратор переписывает при каждой выгрузке; неизменённая берётся из кэша за доли
секунды. XML правили руками — загрузить с `force: true`. Что обновление сломало в правилах — загрузить новую
выгрузку под новым идентификатором, `structure_compare` со старой и `rules_validate` правил против новой.

## 3. Как ставить задачу агенту

Пишите обычным языком, называя план обмена, направление и структуры:

- **Добавить объект в обмен**
  > Через kd-rules-mcp добавь в правила обмена `ОбменЗарплата3Бухгалтерия3` (БП → ЗУП) перенос справочника
  > «Должности»: ПКО с ПКС по кандидатам и ПВД. Структуры: источник `bp-full`, приёмник `zup-full`. Сохрани в
  > `workspace\zup\ПравилаОбмена.xml`, прогони чек-лист проверок, отчёт — что включил, что выключил и почему.
- **Проверить готовые правила**
  > Проверь правила `…\Templates\ПравилаОбмена\Ext\Template.txt` против структур `bp-full` / `zup-full`,
  > разбери замечания: что дефект правил, что расхождение конфигураций.
- **Разобрать проблему живого обмена** (скилл `kd2-exchange-pitfalls`)
  > В ДО задваиваются контрагенты из БП. Вот правила, выгруженные из обеих баз: `…\bp.zip`, `…\do.zip`.
  > Найди причину по правилам и коду БСП, предложи минимальную правку.
- **Разобрать обмен через универсальный формат** (скилл `kd3-rules`)
  > Через kd-rules-mcp разбери, почему в обмене через универсальный формат из БП в ЗУП не переносится реквизит
  > «Комментарий» справочника «Должности»: найди правила в модулях менеджеров обеих сторон, проверь связность и
  > свойство в схеме формата версии обмена. Что проверено чтением, а что нет — скажи отдельно.
- **Правила регистрации**
  > Пересобери правила регистрации плана `ОбменЗарплата3Бухгалтерия3` по ПВД его правил обмена, сравни с макетом.
- **Обратное направление**
  > Построй черновик правил корреспондента для ПКО «Сотрудники»; перечисли обработчики для ручного переноса.

Агент **не переносит** результат в проект 1С сам — это отдельный шаг по правилам проекта (захват в хранилище,
замена `ExchangePlans\<План>\Templates\…\Ext\Template.txt`, обновление базы).

## 4. Проверки перед переносом

| Проверка | Как | Хорошо, если |
|---|---|---|
| Формат, структуры, ссылки на алгоритмы, параметры поиска | `rules_validate` с обеими структурами | нет **новых** замечаний относительно исходных правил |
| Синтаксис кода обработчиков | `handlers_export` → внешний синтакс-чекер 1С (MCP) → `handlers_locate` | нет ошибок разбора |
| Штатная загрузка в базу КД | `uv run python kdbase\kd_check.py check <файл>` | `ИТОГ OK`, число ПКО/ПВД ожидаемое |
| Штатная загрузка правил БСП (без записи в базу) | `uv run python kdbase\bsp_check.py <правила> <правила корреспондента> --plan <план> --project <проект> --base <песочница>`; готовый архив (`rules_pack`, 2 или 3 файла) — `--archive <ZIP>` вместо пары файлов | `ИТОГ OK` |
| Живой обмен между песочницами (поиск в приёмнике, дубли) | `uv run python kdbase\exchange_check.py run --plan <план> --source <проект>.<база> --target <проект>.<база> --object <Документ.Имя> --ref <идентификатор> --source-rules <ZIP> --target-rules <ZIP> --query "<запрос>" --expect-rows N` | `ИТОГ OK`, запрос в приёмнике вернул ожидаемое |
| Живой обмен через универсальный формат | `uv run python kdbase\ed_exchange_check.py run --source <проект>.<база> --target <проект>.<база> --case <случай.json>` | `ИТОГ OK`: значение есть в новом сообщении и в приёмнике |

Что каждая проверка доказывает и чего не доказывает, где запускается и что ей нужно (база КД в `base\`, логины
песочниц, серверы данных баз), как читать итог, типичные ложные замечания и все идентификаторы проверок
`rules_validate` — **[docs/checks.md](docs/checks.md)**. `bsp_check`, `exchange_check` и `ed_exchange_check` работают только с базами
роли «песочница» (`run` и `cleanup`); порядок живой проверки и грабли — скилл `kd2-exchange-pitfalls` (КД 2) и `kd3-rules` (универсальный формат).
Случай `ed_exchange_check` может задать тип приёмника и имя типа формата отдельно от типа источника.

### Дополнительные живые проверки `kdbase`

Через серверы данных баз (`data_mcp`, инструмент `vcexecutecode`), только в песочницах:

```powershell
uv run python kdbase/rules_dump.py --base <проект>.<база> --plan <план> --out <каталог>
uv run python kdbase/plans_overview.py --base <проект>.<база>
uv run python kdbase/exchange_check.py register --base <проект>.<база> --object <Справочник.Имя> --ref <UUID> --restore
uv run python kdbase/exchange_check.py delete --plan <план> --source <проект>.<база> --target <проект>.<база> --object <Справочник.Имя> --ref <UUID> --mode mark --confirm
uv run python kdbase/exchange_check.py delete --plan <план> --source <проект>.<база> --target <проект>.<база> --object <Справочник.Имя> --ref <UUID> --mode delete --expect deleted --confirm
```

`rules_dump` читает действующие записи, раскрывает хранилища XML в базе и получает base64 частями
с проверкой размера/SHA256. В каталоге прогона — XML под именами `rules_pack` и `rules.zip`.
По каждому виду выводятся источник, макет/файл, признак загрузки, сведения и размер.
Отсутствие записи — штатный результат; неполный архив явно обозначается.
`plans_overview` только читает: подключение к БСП, XML/универсальный формат, РИБ, три стандартных
макета (пустота — нулевой размер), записи регистра с источниками и количество узлов кроме этого.

`register` читает регистрацию до/после обычной записи, выводит добавленные узлы каждого плана;
`--plan` ограничивает наблюдение, `--restore` снимает только добавленные пары узел/объект и проверяет
результат. Побочные действия подписок не откатываются. На время прогона исключите параллельную
регистрацию и фоновый обмен этого объекта.

`delete` меняет только объект `--ref` в источнике, затем обменивается и сравнивает состояние
объекта приёмника. Узлы нужно заранее подготовить через `exchange_check setup`.
Без `--confirm` — предпросмотр без обращения к базам, код 2. Для `mark` ожидается `marked`,
для `delete` обязателен `--expect marked|deleted|kept`.
Если тип или UUID объекта приёмника отличаются, укажите `--target-object` и `--target-ref`;
объект должен существовать до начала проверки. Как `run`, команда очищает накопленные регистрации
узла приёмника в источнике. Ошибка удаления останавливает следующие стадии.
Допустимы ZIP `--source-rules`/`--target-rules` и контрольный `--query`/`--expect-rows` как у `run`.

Каждая стадия имеет итог в stdout; завершение — `ИТОГ OK|ОШИБКА`, `КОНЕЦ`, код 0/1.
Поведение БСП со ссылками на строки, ограничения и подробные стадии — [docs/checks.md](docs/checks.md).
Тесты без баз не заменяют живой прогон принимающего.

## 5. Если что-то не так

| Симптом | Причина и что делать |
|---|---|
| `structure_not_found` | структура не загружена — в ответе список загруженных; загрузить `structure_load_project` |
| `project_config` | ошибка в `projects.yaml` или неизвестный проект/конфигурация/база — текст говорит, что есть |
| «Путь серверу не виден» / «Папка проекта не задана» | папка не подключена: добавить проект в `projects.local.yaml`, `setup_local.py`, `docker compose up -d` |
| `object_not_found` | опечатка в имени объекта — в ответе `suggestions`; формат `Справочник.Имя` или `СправочникСсылка.Имя` |
| `path_outside_workspace` | сохранять можно только в `workspace\` — путь в ответе |
| Проекты правил пропали | после перезапуска контейнера открытые проекты теряются; сохраняйте результат `rules_save` ([рабочая папка и проекты правил](docs/workflow.md)) |
| Ответ `match_objects` огромный | сузить `text` и `kind` |
| «Неверно указан пользователь или пароль» в `bsp_check` | задать логин базы (`logins` или `.dev.env` проекта) |
| `exchange_check`: «пустой ответ сервера данных» | в базе нет инструмента `vcexecutecode` у сервера данных — включить его в настройках сервера данных базы |
| `ed_exchange_check`: «пустой ответ сервера данных» | код ушёл не одной строкой или не в UTF-8, либо у сервера данных нет инструмента выполнения кода |
| Агент не видит инструменты | `docker compose ps`; в Claude Code — одобрить сервер (`claude mcp list`) |

## 6. Ограничения

- Для КД 3 сервер пишет собственный модуль правил и расширение-надстройку над типовым, но не правит типовой
  модуль на месте; собственный тип формата (расширение схемы XDTO) не строит — поля без места в формате идут через
  `AdditionalInfo`.
- Код обработчиков пишет агент; сервер проверяет его область видимости, сравнения перечислений формата и
  обязательные свойства, синтакс-чекер — синтаксис; смысл проверяет только живой обмен в песочницах. В переносе
  84 правил три дефекта нашлись только обменом.
- Установка расширения и правил регистрации в базу — за человеком (или агентом с доступом к конфигуратору);
  сервер пишет комплект и инструкцию.
- Черновик корреспондента — основа (около двух третей пар совпадает с ручными правилами); обработчики и
  асимметричные решения — за агентом.

## План развития

Задачи — в [Issues](https://github.com/egordoronchenko/kd-rules-mcp/issues), доска —
[kd-rules-mcp — план развития](https://github.com/users/egordoronchenko/projects/1). Версия 1.0.0 закрыла
цель «КД 2 и собственный модуль КД 3 через агента»; 1.1.0 — переименование, готовый образ, комплект в
существующее расширение пользователя и проверки по находкам живого обмена; 1.2.0 — расширение формата
(собственный пакет XDTO в комплекте, проверено живым обменом и загрузкой в КД 3); дальше — то, что принесут новые
переносы. Что сделано по версиям —
[CHANGELOG.md](CHANGELOG.md).

## Разработка

```powershell
uv sync
uv run ruff format; uv run ruff check; uvx pyright
uv run pytest
```

Быстрый прогон без тестов с меткой `slow`: `uv run pytest -q -m "not slow"`. Готовность задачи проверяет полный `uv run pytest`.

Тесты на синтетических данных (`tests/data`) идут всегда. Остальные включаются переменными окружения, без них
пропускаются с причиной:

| Переменная | Что включает |
|---|---|
| `KD2_CORPUS_DIRS` | round-trip и проверки на реальных макетах правил: каталоги XML-выгрузок конфигураций с `ExchangePlans`, через `;`. По умолчанию — выгрузки проектов из `projects.yaml` с папками из `projects.local.yaml` |
| `KD2_REFERENCE_DIR` | сверки с эталоном формата: XML-выгрузка конфигурации «Конвертация данных» 2.1. По умолчанию — `reference\kd2-cfg`, если есть |
| `KD2_DEPLOY_URL` | тесты развёрнутого контейнера (`http://localhost:8060/mcp`) |
| `KD2_KDBASE_CHECK=1` | прогон через базу КД (`kdbase`) |

Устройство сервера — слои и модули, поток данных, инварианты, границы, развёртывание и безопасность, как добавить
инструмент или проверку — **[docs/architecture.md](docs/architecture.md)**.

Разборы формата и обоснования проверок — `docs/research/`; главный — `kd2-format-digest.md`. Ссылки вида
`reference/kd2-cfg/…:N` в коде и документах — строки XML-выгрузки конфигурации КД 2.1.8.2. Серверу она не нужна;
она нужна только разработчику, который сверяет новые факты о формате по эталону. В репозитории её нет — это
продукт фирмы 1С; выгрузите её Конфигуратором из своей базы КД в `reference\kd2-cfg`.
Правила для агентов-разработчиков — `AGENTS.md`.

## Лицензия

MIT — см. [LICENSE](LICENSE). «1С», «1С:Предприятие», «Конвертация данных», БСП — продукты и товарные знаки
фирмы «1С»; конфигураций и поставки КД в репозитории нет (в тестовых данных — короткие выдержки формата).