> For the complete documentation index, see [llms.txt](https://docs.onerpa.ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onerpa.ru/mcp-servery-1c/servery/kd20.md). # Конвертация данных 2.0 (KD20) KD20 помогает ИИ писать и дорабатывать правила обмена «Конвертации данных» 2.0/2.1 между двумя конфигурациями 1С. Сервер подбирает соответствия объектов и реквизитов, собирает правила конвертации, выгрузки и регистрации, проверяет их по метаданным обеих конфигураций и по поведению исполнителя правил БСП. Готовые макеты правил он читает без потерь и записывает обратно в стиле «Конвертации данных». Сервер детерминированный: он разбирает, предлагает кандидатов, пишет XML и проверяет. Что во что конвертировать, решает ИИ — и показывает решения в отчёте и в диффе с исходными правилами. Обмен через универсальный формат (EnterpriseData, «Конвертация данных» 3) сервер читает и проверяет, но не пишет: модуль менеджера обмена из выгрузки конфигурации, схему формата из пакетов XDTO, связность правил и их соответствие схеме и конфигурации. С копией базы через её сервер данных (Конструктор MCP-серверов 1С) сервер по желанию проверяет загрузку правил, снимает правила, которые действуют в базе, показывает планы обмена и проверяет, куда регистрируется объект, — только чтением или в транзакции, которая всегда отменяется. Две базы, между которыми идёт обмен, задаются в самом сервере: где база находится, пользователь и пароль, платформа, сервер данных и признак копии. Обмен — пара баз «источник → приёмник» с технологией (КД 2 или КД 3) и планами обмена сторон. Сервер возвращает строку запуска и строку соединения каждой базы и через сервер данных проверяет, что это та база и что её планы обмена подходят обмену. ## Поставка и требования * Образ: `comol/1c_conversion_data_mcp`, версия **0.5.0**; теги `latest` (Linux/amd64) и `arm64` (Linux/arm64), других тегов на Docker Hub нет. Варианта `light` нет: embeddings сервер не использует. При `IMAGE_VARIANT=light` ставится `latest`. * Ключ в `config.env`: `LICENSE_KEY_KD20`; внутри контейнера — `LICENSE_KEY` или путь к файлу ключа в `LICENSE_KEY_FILE`. * Порт: **8009**; MCP: `http://127.0.0.1:8009/mcp` (Streamable HTTP); liveness: `/healthz`. * Имя MCP-подключения: `1c-kd20`. * Вход — выгрузки конфигураций, а не базы: выгрузка Конфигуратора в файлы XML (`Configuration.xml`) или проект 1C:EDT (`Configuration.mdo`) для источника и приёмника. При доработке — готовые правила: макет плана обмена `ExchangePlans\<План>\Templates\ПравилаОбмена\Ext\Template.txt` (он уже есть в выгрузке конфигурации), `ExchangeRules.xml`, `RegistrationRules.xml`. Для обмена через универсальный формат — та же выгрузка: модуль менеджера обмена (`CommonModules\<Модуль>`) и пакеты XDTO `EnterpriseData_*`. * Embeddings, LLM API, платформа 1С и сама «Конвертация данных» не нужны. Для проверок в 1С нужна копия базы с сервером данных — Конструктор MCP-серверов 1С с инструментами `vcexecutecode` (1c-data-mcp); без него четыре инструмента проверок в 1С отвечают отказом. ## Что умеет | Группа | Инструменты | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Базы и обмены | `set_base`, `describe_bases`, `delete_base`, `base_launch_string`, `check_base_in_1c`, `set_exchange`, `describe_exchanges`, `delete_exchange` | | Конфигурации | `load_configuration`, `list_configurations`, `list_metadata`, `describe_object`, `compare_configurations` | | Подбор соответствий | `suggest_object_mappings`, `suggest_property_mappings` | | Набор правил | `create_ruleset`, `draft_ruleset`, `list_rulesets`, `describe_ruleset`, `set_object_rule`, `delete_object_rule`, `set_object_rules_flags`, `set_property_rule`, `delete_property_rule`, `set_value_map`, `set_export_rule`, `delete_export_rule`, `set_clear_rule`, `set_conversion_handler`, `set_parameter`, `set_algorithm`, `set_query`, `bind_configurations`, `draft_correspondent_ruleset` | | Проверка и выгрузка | `validate_ruleset`, `generate_rules_xml`, `preview_rules_xml`, `import_rules_xml`, `diff_rulesets`, `pack_rules_zip`, `export_handlers_bsl`, `locate_handler_line` | | Проверки в копии базы (необязательно) | `check_rules_in_1c`, `dump_rules_from_1c`, `exchange_plans_in_1c`, `check_registration_in_1c` | | Навигация по готовым правилам | `search_ruleset_code`, `read_handler`, `trace_object`, `handler_queries` | | Правила регистрации | `import_registration_rules`, `build_registration_rules`, `validate_registration_rules`, `describe_registration_rules`, `generate_registration_xml` | | Обмен через универсальный формат (КД 3), только чтение | `ed_open`, `ed_overview`, `ed_list`, `ed_get`, `ed_locate`, `ed_validate`, `ed_close`, `ed_schema_open`, `ed_schema_types`, `ed_schema_type`, `ed_schema_close` | | Справка | `handler_interface`, `kd20_format_reference`, `search_kd20`, `explain_kd20`, `index_kd20_path` | * **Две базы обмена.** `set_base` задаёт базу: где она находится — каталог файловой базы (`file_path`), кластер и имя базы на сервере 1С (`server` + `ref`) или веб-публикация (`web_url`), — пользователя и пароль, платформу (версию, каталог или `1cv8.exe`), сервер данных базы (`data_server_url`) и признак копии (`sandbox=true`). `set_exchange` связывает две базы в обмен: источник и приёмник, технология `КД2` (правила обмена XML) или `КД3` (EnterpriseData, с версией формата), планы обмена сторон и для КД 2 — правила этого направления, корреспондента и регистрации. `describe_exchanges` возвращает и `шаги` — вызовы инструментов KD20 для этого обмена с заполненными аргументами. `base_launch_string` даёт командную строку запуска (Предприятие или Конфигуратор, толстый или тонкий клиент), программу и аргументы отдельно и строку соединения (`File=…;`, `Srvr=…;Ref=…;`, `ws=…;`) для COM и `/IBConnectionString`; пароль — маской, настоящий только с `include_password=true`. Если задана только версия платформы, путь строится для 64-разрядной установки (`C:\Program Files\1cv8\<версия>\bin`), а 32-разрядная названа в примечании; сервер, запущенный не в контейнере, сам выбирает существующий из двух путей. `check_base_in_1c` через сервер данных базы (только чтение) получает конфигурацию и версию, платформу, версию БСП, строку соединения базы и по планам обмена — подключён ли план к БСП, технологию (XML или универсальный формат) и версии формата EnterpriseData — и сверяет с профилем: та ли это база, не устарел ли снимок конфигурации в KD20, подходят ли технология и версия формата обмену. Инструменты проверок в 1С принимают `base` вместо адреса сервера данных; проверки с записью в отменяемой транзакции (`check_rules_in_1c`, `check_registration_in_1c`) по `base` выполняются только в базе с `sandbox=true`. Проверено на копии ЗУП КОРП 3.1.26.13: база сообщила платформу 8.3.27.2130 и БСП, план `ОбменЗарплата3Бухгалтерия3` — XML, план `СинхронизацияДанныхЧерезУниверсальныйФормат` — универсальный формат с версиями 1.15, 1.11, 1.10, 1.8, 1.3; неверное расположение и неподдерживаемая версия формата попали в замечания. * **Импорт без потерь.** Группы правил (папки дерева КД), `Обработки`, варианты поиска, все поля, которые пишет КД 2.1, и неизвестные узлы сохраняются. Стиль исходного файла (BOM, переводы строк, отступ) повторяется при записи: доработка макета даёт минимальный дифф. На макетах планов обмена ЗУП и ERP запись совпадает с исходником по смыслу во всех файлах, а файлы, записанные КД 2.1, воспроизводятся побайтно. * **Проверка `validate_ruleset`.** Формат КД 2.0, метаданные обеих конфигураций и поведение исполнителя БСП: * ссылочное свойство без ПКО своего типа — исполнитель молча пропускает значение; * примитив (строка, число) в объектную ссылку; * значения ПКЗ, которых нет у перечисления, и значения без ПКЗ; * алгоритм не того режима: обработчик загрузки вызывает алгоритм выгрузки и наоборот; * параметр, который читает `ПоследовательностьПолейПоиска`, а ПКС передаёт его без флага «Поиск» — типичная причина дублей; * вызов из кода ПКО, которого нет (`ИмяПКО = "…"`, имя ПКО в аргументе `ВыгрузитьПоПравилу`, `ВыгрузитьРегистр`, `ВыгрузкаОбъектаВыборки`, в том числе в `?(…)` и `Выполнить("…")`); * `ПараметрыОбъекта.Имя` через точку — это `Соответствие`, обмен упадёт; * объекты выборки ПВД и ПОД, неиспользуемые правила (в том числе ПКО, которое по типу значения перекрывает более позднее ПКО того же источника), длина строк, необъявленные параметры, два алгоритма или запроса с одним именем в одном режиме, дубли кодов ПВД, ПОД и параметров; * ПКО перечисления без единого ПКЗ (приходит пустая ссылка); иерархия без «ЭтоГруппа» в поиске (группы приходят элементами); подчинённый справочник без «Владелец» в поиске; проводимый документ без ПКС «Проведен» (приходит непроведённым); две группы ПКС на одну табличную часть; `ОбъектМодифицирован = Ложь`, `НеОчищать` у табличной части и `ДопОбработки`, которые ничего не делают; отключённая группа ПВД, правила которой всё равно выполняются; имя и версия конфигурации в заголовке правил против выгрузки. Отдельно — то, как правила исполняет обмен через план обмена БСП (в отличие от ручного обмена обработкой «Универсальный обмен данными в формате XML»): * второй ПВД на тот же тип не выполняется — работает первый включённый; * способ отбора «произвольный алгоритм», `ВыборкаДанных` и `Отказ = Истина` в «ПередОбработкойПравила» не исполняются; * формы поиска, которые дают дубли или сливают объекты: единственное поле «ЭтоГруппа», обработчик поиска, до которого не доходит дело, продолжение поиска без полей, имя в `СтрокаИменСвойствПоиска` не из свойств поиска; * `Объект.Записать()` в «ПослеЗагрузки» — запись до режима загрузки, объект пишется дважды; * объект, который уходит только ссылкой (в приёмник попадают лишь поля поиска); с `registration_name` учитывается режим выгрузки «при необходимости» из правил регистрации. Свойство поиска — ПКС с «Поиск» или «Обязательное». Код отключённых ПВД, ПОД и ПКС не проверяется, ошибка в алгоритме, который ничем не вызывается, понижается до предупреждения. Пока есть ошибки, `generate_rules_xml` файл не пишет (кроме явного `allow_errors=true`). * **Проверка в 1С.** `check_rules_in_1c` загружает правила обмена, корреспондента и регистрации тем же методом БСП, что форма загрузки правил плана обмена (`РегистрыСведений.ПравилаДляОбменаДанными.ЗагрузитьПравила`), — в копии базы через её сервер данных (1c-data-mcp, инструмент `vcexecutecode`). Правила попадают только в запись регистра в памяти, весь код выполняется в транзакции, которая всегда отменяется. Ответ: загружены ли правила, информация о правилах и причина отказа — сообщение БСП, исключение или запись журнала регистрации («Ошибка формата правил обмена»). Проверено на копии ЗУП КОРП 3.1.26: типовые правила `ОбменЗарплата3Бухгалтерия3` после импорта и записи сервером и черновик, собранный сервером с нуля, загружаются; испорченные правила отвергаются с причиной. * **Правила, которые действуют в базе.** `dump_rules_from_1c` снимает из регистра `ПравилаДляОбменаДанными` копии базы правила плана обмена: откуда они (макет конфигурации или файл), загружены ли и сам XML правил обмена, корреспондента и регистрации — частями со сверкой SHA-256; с `import_as` сразу загружает их в наборы, и `diff_rulesets` показывает отличие от макета. `exchange_plans_in_1c` — обзор планов обмена: узлы, источник правил, предупреждение о несоответствии версий, выборочная регистрация. Оба только читают. На копии ЗУП КОРП 3.1.26 выяснилось, что в базе загружены правила `ОбменЗарплата3Бухгалтерия3` 2015 года, а не текущий макет. * **Куда регистрируется объект.** `check_registration_in_1c` показывает получателей по действующим правилам регистрации и записывает объект обычной записью в транзакции, которая всегда отменяется; после отката регистрация сверяется с исходной. Побочные действия подписок вне базы (файлы, внешние вызовы, сообщения) не откатываются — только копия базы. * **Правила регистрации.** Сборка по ПВД и составу плана обмена с сохранением существующих правил; отборы по свойствам плана и объекта задаются прямо в описании объекта (группы «И» и «ИЛИ», константа, `[ТЧ].Реквизит`, режим выгрузки). Проверка: объект есть и входит в состав плана, свойства отборов и реквизит режима выгрузки существуют; объект ПВД вне состава плана; объект ПВД без правила регистрации (БСП регистрирует его на всех узлах); авторегистрация, при которой отборы не действуют; объект регистрируется, а включённого ПВД нет — записи копятся в очереди узла; правило без `Валидное` не загрузится; группа отбора без оператора, неизвестный вид сравнения и порядок узлов константы, которые загрузчик БСП прочитает не так. Отключение группы правил, как и в БСП, на правила внутри неё не влияет. `pack_rules_zip` собирает ZIP комплекта для формы загрузки правил плана обмена. * **Умолчания как в КД 2.1.** Новое ПКО со ссылочным приёмником получает синхронизацию по идентификатору, ПКС «ЭтоГруппа» — «Обязательное»; поставленное по умолчанию видно в ответе. Черновик поэтому по умолчанию без полей поиска; для первой синхронизации баз, где данные уже есть, передайте `sync_by_id=false` или задайте свойства поиска с продолжением поиска. * **Подбор пар.** Для объекта, у которого нет кандидата по имени, предлагается объект с тем же составом реквизитов (переименование, не меньше 70 % общих реквизитов). * **Навигация.** `trace_object` показывает путь объекта через правила с каскадом значений вглубь (`depth`), целиком или только ссылкой уходит значение, цепочку «ветка → алгоритм → вызов ПКО» с номерами строк, ПВД, вместо которого при обмене через план работает другой, реквизит режима выгрузки, попадание в очередь узла и что появится в приёмнике. `handler_queries` разбирает запросы в коде правил: пакет, временные таблицы и их зависимости, параметры, какой запрос читает `Результат[n]`. `search_ruleset_code` ищет и в соответствиях ПКС, и в отборах правил регистрации, с отборами и постранично. * **Обмен через универсальный формат (КД 3).** `ed_open` открывает модуль менеджера обмена из выгрузки (ЗУП — 0,2 с, ERP на 104 тыс. строк — около 4 с), `ed_list` / `ed_get` / `ed_locate` показывают правила (ПКО, ПКС, ПКТЧ, ПОД, ПКПД), обработчики и ветки диспетчера; `ed_schema_open` читает схему формата EnterpriseData из пакета XDTO. `ed_validate` проверяет по исполнителю БСП (`ОбменДаннымиXDTOСервер`) связность модуля, правила против схемы формата и против конфигурации. На типовых модулях ЗУП и ERP нашлись ключи `ИспользованиеПКО`, которых нет в ИспользуемыеПКО, обработчики без веток диспетчера, ПКС на несуществующий реквизит и ПКС получения со ссылкой на ПКПД отправки. * **Код обработчиков.** `export_handlers_bsl` выгружает каждый обработчик и алгоритм отдельным BSL-модулем с параметрами обработчика — для [SyntaxCheckServer](/mcp-servery-1c/servery/syntax-check-server.md); `locate_handler_line` переводит строку замечания в правило и строку обработчика. * **Обратное направление.** `draft_correspondent_ruleset` строит черновик правил корреспондента: ПКО, ПКС и ПКЗ зеркалируются, обработчики возвращаются списком для ручного переноса. * **Справка о граблях обменов.** `kd20_format_reference(section="грабли")`: случаи живых обменов (дубли, не найденный объект, транзакции загрузки, ветки выгрузки при обмене через план, объект по ссылке, проведение и удаление при загрузке, табличные части, регистрация, какие правила действуют в базе) с причиной по коду БСП, проверкой и исправлением; разделы `протокол` (код ошибки протокола обмена → правило), `жалобы` (жалоба словами → что проверить первым), `фазы` (где вызывается обработчик и что делает `Отказ`) и `кд3_грабли` (обмен через универсальный формат). Обработчики загрузки приёмник исполняет из своей копии правил корреспондента, а не из правил в сообщении: ошибку загрузки правят в правилах отправителя и перезагружают комплект в приёмнике. ## Ограничения * Писать сервер умеет только правила формата 2.01 («Конвертация данных» 2.0/2.1). Обмен через универсальный формат (КД 3) — только чтение и проверка модуля менеджера; слои расширений конфигурации и маршруты версий формата не читаются. * С базами 1С сервер работает только через сервер данных копии базы: проверочная загрузка правил и регистрация объекта — в транзакции с откатом, снятие правил и обзор планов — только чтением. Живой обмен между копиями баз и загрузку правил в базу КД выполняют вручную. * Базы сервер не запускает: строку запуска исполняет ИИ-агент на вашей машине. Пути в профиле базы (каталог файловой базы, платформа) — пути этой машины, сервер в контейнере их не проверяет. * Пароль базы хранится в профиле в рабочих данных сервера (`PATH_BASES\kd20\bases`, в контейнере `/data/bases`) открытым текстом. В ответы инструментов он не попадает, кроме строки запуска с `include_password=true`; каталог профилей закрыт для инструментов, читающих файлы, и для поискового индекса. Серверу данных логин и пароль передаются только с `data_server_auth=true` — если публикация `…/hs/mcp` требует Basic-аутентификацию. * Состав плана обмена для правил регистрации читается из выгрузки Конфигуратора (`ExchangePlans\<План>\Ext\Content.xml`); из проекта 1C:EDT — пока нет. * Синтаксический анализатор не доказывает, что переменные контекста обработчика использованы верно: смысл проверяет только обмен. * Перенос результата в проект 1С (захват в хранилище, замена `Template.txt`, обновление базы) выполняется по правилам проекта, а не этим сервером. ## Установка (PowerShell) Готовый сценарий установки — `servers/09_KD20.md` в дистрибутиве MCP\_Distr (ИИ-агент выполняет его по `INSTALL.md`). В `config.env` заполните: * `LICENSE_KEY_KD20` — ключ сервера; * `KD20_WORKSPACE` — папка, где лежат выгрузки конфигураций и макеты правил; монтируется в контейнер только на чтение как `/workspace`; * `PATH_BASES` — рабочие данные сервера пойдут в `PATH_BASES\kd20`, готовые файлы правил — в `PATH_BASES\kd20\output`; * `KD20_HTTP_PORT` — порт, по умолчанию `8009`. ```powershell docker run -d --name 1c_kd20_mcp --init --restart unless-stopped ` -e LICENSE_KEY=ВАШ_КЛЮЧ ` -e "KD20_PATH_MAP=E:\Dumps=/workspace;E:\bases\mcp\kd20=/data" ` -e KD20_SANDBOX_DATA_URL=http://host.docker.internal/zup_copy/hs/mcp ` --add-host host.docker.internal:host-gateway ` -p 127.0.0.1:8009:8009 ` -v "E:\Dumps:/workspace:ro" ` -v "E:\bases\mcp\kd20:/data" ` comol/1c_conversion_data_mcp:latest ``` `KD20_PATH_MAP` сопоставляет пути этой машины путям контейнера: ИИ передаёт пути так, как они выглядят у вас (`E:\Dumps\ЗУП`), а сервер переводит их сам и в ответах возвращает пути вашей машины. Проверка: `curl http://127.0.0.1:8009/healthz` возвращает `{"service":"kd20-mcp","status":"ok","check":"liveness"}`. `Exited (1)` сразу после старта — неподходящий ключ (`docker logs 1c_kd20_mcp` покажет `Invalid LICENSE_KEY`). Подключение клиента (ключ в `mcp.json` не пишется), клиент видит 71 инструмент: ```json {"mcpServers":{"1c-kd20":{"url":"http://127.0.0.1:8009/mcp"}}} ``` ## Как ставить задачу * **Две базы обмена.** «Задай в 1c-kd20 базы ЗУП (файловая `E:\Bases\ZUP_copy`, сервер данных `http://host.docker.internal/zup_copy/hs/mcp`, это копия) и БП (сервер `srv01`, база `bp_copy`), обмен ЗУП → БП по плану `ОбменЗарплата3Бухгалтерия3`, проверь обе базы и дай строку запуска ЗУП». * **Новые правила.** «Через 1c-kd20 загрузи выгрузки `E:\Dumps\БП` и `E:\Dumps\ЗУП`, собери черновик правил обмена по справочникам и документу `ВедомостьНаВыплатуЗарплаты`, проверь и сформируй файл правил». * **Доработка макета.** «Импортируй макет `E:\Dumps\ЗУП\ExchangePlans\ОбменЗарплата3Бухгалтерия3\Templates\ПравилаОбмена\Ext\Template.txt`, привяжи конфигурации, проверь до правок, добавь перенос справочника «Должности», покажи дифф с макетом и запиши правила в стиле КД». * **Разбор жалобы на обмен.** «В приёмнике задваиваются контрагенты: найди ПКО, проверь свойства поиска и обработчик `ПоследовательностьПолейПоиска`». * **После обновления конфигурации.** «Загрузи новую выгрузку под другим именем, сравни со старой (`compare_configurations`) и проверь правила против новой». * **Правила в базе не те.** «Сними правила обмена `ОбменЗарплата3Бухгалтерия3` из копии базы и сравни с макетом из выгрузки». * **Обмен через EnterpriseData.** «Открой модуль `МенеджерОбменаЧерезУниверсальныйФормат` из выгрузки `E:\Dumps\ЗУП`, схему `EnterpriseData_1_10_8` и проверь правила против схемы и конфигурации». Порядок работы над макетом: `import_rules_xml` → `bind_configurations` → `validate_ruleset` (запомнить исходные замечания) → правки → `validate_ruleset` (нет новых замечаний) → `diff_rulesets` с исходным макетом → `check_rules_in_1c` в копии базы → `generate_rules_xml(style="kd")` → `export_handlers_bsl` и SyntaxCheckServer, если менялся код обработчиков. ## Переменные окружения | Переменная | Назначение | В образе | | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | `LICENSE_KEY` / `LICENSE_KEY_FILE` | лицензионный ключ или файл с ним | обязателен | | `KD20_HTTP_PORT`, `KD20_HOST` | порт и адрес HTTP | `8009`, `0.0.0.0` | | `KD20_PATH_MAP` | `путь_машины=путь_контейнера;…` | не задано | | `KD20_DATA`, `KD20_OUTPUT`, `KD20_DB` | рабочие данные, файлы правил, поисковый индекс | `/data`, `/data/output`, `/data/kd20.sqlite3` | | `KD20_ALLOWED_ROOTS` | где разрешено читать и писать (через `;`) | `/data;/workspace` | | `MCP_TRANSPORT` | `http` или `stdio` | `http` | | `KD20_SANDBOX_DATA_URL` | сервер данных копии базы (1c-data-mcp, `…/hs/mcp`) для `check_rules_in_1c`, `dump_rules_from_1c`, `exchange_plans_in_1c`, `check_registration_in_1c` (у каждого есть и параметры `data_server_url` и `base` — база из `set_base`); из контейнера база на этой машине — `host.docker.internal` | не задано | Справочники сервера в поисковом индексе обновляются при каждом запуске: заменяются только их фрагменты, проиндексированное через `index_kd20_path` остаётся (справочники — формат правил, обработчики, грабли обменов КД 2 и обмена через универсальный формат). Контейнер работает от пользователя с uid 10001. ## Состав образа Модули сервера скомпилированы Cython; исходниками в образе остаются только `__init__.py` (версия), `__main__.py` (запуск) и `exposure.py` — обёртки, через которые FastMCP регистрирует скомпилированные функции инструментов. При сборке схемы всех инструментов скомпилированного сервера сверяются с исходными, а тесты сервера выполняются на скомпилированных модулях.