Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Конвертация данных 2.0 (KD20)

KD20 помогает ИИ писать и дорабатывать правила обмена «Конвертации данных» 2.0/2.1 между двумя конфигурациями 1С. Сервер подбирает соответствия объектов и реквизитов, собирает правила конвертации, выгрузки и регистрации, проверяет их по метаданным обеих конфигураций и по поведению исполнителя правил БСП. Готовые макеты правил он читает без потерь и записывает обратно в стиле «Конвертации данных».

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

Поставка и требования

  • Образ: comol/1c_conversion_data_mcp, версия 0.3.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.

  • Embeddings, LLM API, платформа 1С и сама «Конвертация данных» не нужны. Для проверки правил загрузкой в 1С нужна копия базы с сервером данных (1c-data-mcp).

Что умеет

Группа
Инструменты

Конфигурации

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, check_rules_in_1c, generate_rules_xml, preview_rules_xml, import_rules_xml, diff_rulesets, export_handlers_bsl, locate_handler_line

Навигация по готовым правилам

search_ruleset_code, read_handler, trace_object

Правила регистрации

import_registration_rules, build_registration_rules, validate_registration_rules, describe_registration_rules, generate_registration_xml

Справка

handler_interface, kd20_format_reference, search_kd20, explain_kd20, index_kd20_path

  • Импорт без потерь. Группы правил (папки дерева КД), Обработки, варианты поиска, все поля, которые пишет КД 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 после импорта и записи сервером и черновик, собранный сервером с нуля, загружаются; испорченные правила отвергаются с причиной.

  • Правила регистрации. Сборка по ПВД и составу плана обмена с сохранением существующих правил и отборов; проверка: объект есть и входит в состав плана, свойства отборов существуют; объект ПВД вне состава плана (в очередь узла не попадает); объект ПВД без правила регистрации (БСП регистрирует его на всех узлах без отборов); правило регистрации объекта с разрешённой авторегистрацией (отборы не действуют). Отключение группы правил, как и в БСП, на правила внутри неё не влияет.

  • Навигация. trace_object показывает путь объекта через правила; ПВД, вместо которого при обмене через план работает другой; реквизит режима выгрузки у правила регистрации; попадает ли объект без правила регистрации в очередь узла; общие события конвертации, которые срабатывают для каждого объекта.

  • Код обработчиков. export_handlers_bsl выгружает каждый обработчик и алгоритм отдельным BSL-модулем с параметрами обработчика — для SyntaxCheckServer; locate_handler_line переводит строку замечания в правило и строку обработчика.

  • Обратное направление. draft_correspondent_ruleset строит черновик правил корреспондента: ПКО, ПКС и ПКЗ зеркалируются, обработчики возвращаются списком для ручного переноса.

  • Справка о граблях обменов. kd20_format_reference(section="грабли"): случаи живых обменов (дубли, не найденный объект, транзакции загрузки, ветки выгрузки при обмене через план, объект по ссылке, регистрация) с причиной по коду БСП, проверкой и исправлением. Обработчики загрузки приёмник исполняет из своей копии правил корреспондента, а не из правил в сообщении: ошибку загрузки правят в правилах отправителя и перезагружают комплект в приёмнике.

Ограничения

  • Только правила формата 2.01 («Конвертация данных» 2.0/2.1). КД 3 и EnterpriseData не поддерживаются.

  • С базами 1С сервер работает только через сервер данных копии базы и только для проверочной загрузки правил с откатом. Живой обмен между копиями баз и загрузку правил в базу КД выполняют вручную.

  • Состав плана обмена для правил регистрации читается из выгрузки Конфигуратора (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.

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 не пишется), клиент видит 47 инструментов:

Как ставить задачу

  • Новые правила. «Через 1c-kd20 загрузи выгрузки E:\Dumps\БП и E:\Dumps\ЗУП, собери черновик правил обмена по справочникам и документу ВедомостьНаВыплатуЗарплаты, проверь и сформируй файл правил».

  • Доработка макета. «Импортируй макет E:\Dumps\ЗУП\ExchangePlans\ОбменЗарплата3Бухгалтерия3\Templates\ПравилаОбмена\Ext\Template.txt, привяжи конфигурации, проверь до правок, добавь перенос справочника «Должности», покажи дифф с макетом и запиши правила в стиле КД».

  • Разбор жалобы на обмен. «В приёмнике задваиваются контрагенты: найди ПКО, проверь свойства поиска и обработчик ПоследовательностьПолейПоиска».

  • После обновления конфигурации. «Загрузи новую выгрузку под другим именем, сравни со старой (compare_configurations) и проверь правила против новой».

Порядок работы над макетом: 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; из контейнера база на этой машине — host.docker.internal

не задано

Справочники сервера в поисковом индексе обновляются при каждом запуске: заменяются только их фрагменты, проиндексированное через index_kd20_path остаётся (справочники — формат правил, обработчики, грабли обменов). Контейнер работает от пользователя с uid 10001.

Состав образа

Модули сервера скомпилированы Cython; исходниками в образе остаются только __init__.py (версия), __main__.py (запуск) и exposure.py — обёртки, через которые FastMCP регистрирует скомпилированные функции инструментов. При сборке схемы всех инструментов скомпилированного сервера сверяются с исходными, а тесты сервера выполняются на скомпилированных модулях.

PreviousMCP QA — тестирование 1С
NextИнтеграция

Last updated