KD 2.0 - правила обмена через MCP-toolkit

Скилл описывает, как агент создает/изменяет правила обмена в живой ИБ "Конвертация данных 2.1" (КД 2.0) через MCP-toolkit HTTP API (порт по умолчанию 6003, в проектах часто 7003) и в финале выгружает XML штатными обработками КД.

Что такое КД 2.0

• Конфигурация фирмы "1С", v2.1.8.2, обычные формы, режим совместимости 8.2.13. Программа для разработки правил обмена данными между парами конфигураций (например, БП КОРП -> УПП, УТ -> ERP).
• Результат работы в КД - XML с правилами, который грузится в "Универсальный обмен данными в формате XML" в конфигурации-источнике.
• Все правила хранятся в справочниках самой КД: Конвертации, ПравилаКонвертацииОбъектов, ПравилаКонвертацииСвойств, ПравилаКонвертацииЗначений, ПравилаВыгрузкиДанных, ПравилаОчисткиДанных, ПравилаРегистрацииОбъектов, плюс Конфигурации/Объекты/Свойства/Значения (теневая модель метаданных источника и приемника).

Архитектура работы

Claude (агент)
 ↕ MCP-протокол / прямые tool-вызовы
Скилл kd2-rules
 ↕ HTTP POST :6003/api/* (или :7003 если переопределен порт)
MCP-toolkit (обработка MCP_Toolkit.epf в живой ИБ)
 ↕ внутрипроцессно
ИБ КД 2.0
 ↕ через ВыгрузкаКонвертации.ВыполнитьВыгрузкуПравил
Файл XML с правилами обмена

Низкоуровневый транспорт - MCP-toolkit (скилл 1c-mcp-toolkit). Главные эндпоинты, которые используются здесь:

• POST /api/execute_query - читать справочники КД и их связи.
• POST /api/execute_code - создавать/изменять элементы справочников, запускать экспортные методы обработок.
• GET /api/health - проверка живости.

Предварительные требования

1. Запущенная ИБ КД 2.0 в тонком/толстом клиенте с открытой обработкой MCP_Toolkit.epf (см. скилл 1c-mcp-toolkit). HTTP-сервер слушает localhost:6003 (или :7003 по настройке).
2. В форме toolkit-а проверить и при необходимости снять защиту от записи: снять флажки на ключевые слова Записать, Удалить, УстановитьПривилегированныйРежим. Без этого работают только execute_query и read-only вызовы.
3. Желательно тестовая копия ИБ КД, а не production - правила пишутся напрямую в справочники.

Быстрая проверка готовности

curl http://localhost:7003/health
# Ожидание: {"status":"healthy", ...}

curl -sS -X POST "http://localhost:7003/api/execute_query" \
 -H "Content-Type: application/json" \
 -d '{"query":"ВЫБРАТЬ КОЛИЧЕСТВО(*) КАК Кол ИЗ Справочник.Конвертации"}'

Карта references

Документ	Что внутри	Когда читать
references/helpers.md	библиотека готовых BSL-заготовок для execute_code: списки ПКО/ПКС/ПКЗ, дамп обработчиков, флаги ПКО, ПКС по ссылке на Свойство, выгрузка комплекта XML, поиск объектов с учетом префикса типа, идиомы передачи значений	нужен запрос или правка объектов КД - СНАЧАЛА сюда, не сочинять скрипт с нуля
references/architecture.md	объектная модель КД, иерархия Владелец, полные списки реквизитов всех ключевых справочников	проектирование новой операции, нужны типы и связи
references/methods.md	экспортные методы обработок выгрузки/загрузки + file:line + параметры (реквизиты обработки)	вызов конкретного метода через execute_code
references/workflows.md	end-to-end сценарии: подготовка ИБ, загрузка метаданных, создание правил, выгрузка XML, импорт XML, автонастройка	впервые делаешь полный цикл или сложный сценарий
references/xml-schema.md	схема итогового XML правил обмена + маппинг полей справочника на XML	надо понять, что КД ожидает увидеть в XML, или сверить результат с эталоном
references/troubleshooting.md	типичные ошибки и ограничения toolkit-а, особенности КД 2.0	при ошибке execute_code/execute_query

5 базовых операций (краткий справочник)

1. Найти конвертацию по имени

Конв = Справочники.Конвертации.НайтиПоНаименованию("Имя_Конвертации");
Если Конв.Пустая Тогда
 ВызватьИсключение "Конвертация не найдена";
КонецЕсли;
Результат = XMLСтрока(Конв);

2. Список ПКО в конвертации

curl -sS -X POST "http://localhost:7003/api/execute_query" \
 -H "Content-Type: application/json" \
 -d '{
 "query": "ВЫБРАТЬ ПКО.Наименование, ПКО.ТипИсточника, ПКО.ТипПриемника, ПКО.Порядок ИЗ Справочник.ПравилаКонвертацииОбъектов КАК ПКО ГДЕ ПКО.Владелец.Наименование = &Конв И НЕ ПКО.ЭтоГруппа УПОРЯДОЧИТЬ ПО ПКО.Порядок",
 "params": {"Конв": "Имя_Конвертации"}
 }'

3. Создать ПКО

Конв = Справочники.Конвертации.НайтиПоНаименованию("МояКонвертация");
ОбъИст = Справочники.Объекты.НайтиПоНаименованию("Контрагенты", Истина, Конв.Источник);
ОбъПр = Справочники.Объекты.НайтиПоНаименованию("Контрагенты", Истина, Конв.Приемник);

ПКО = Справочники.ПравилаКонвертацииОбъектов.СоздатьЭлемент;
ПКО.Владелец = Конв;
ПКО.Наименование = "Контрагенты";
ПКО.Источник = ОбъИст;
ПКО.Приемник = ОбъПр;
ПКО.ТипИсточника = "СправочникСсылка.Контрагенты";
ПКО.ТипПриемника = "СправочникСсылка.Контрагенты";
ПКО.Порядок = 100;
ПКО.Записать;

Результат = Новый Структура("ссылка", XMLСтрока(ПКО.Ссылка));

4. Создать ПКС внутри ПКО

ПКО = Справочники.ПравилаКонвертацииОбъектов.НайтиПоНаименованию("Контрагенты", Истина, Конв);
СвИст = Справочники.Свойства.НайтиПоНаименованию("Наименование", Истина, ПКО.Источник);
СвПр = Справочники.Свойства.НайтиПоНаименованию("Наименование", Истина, ПКО.Приемник);

ПКС = Справочники.ПравилаКонвертацииСвойств.СоздатьЭлемент;
ПКС.Владелец = ПКО;
ПКС.Источник = СвИст;
ПКС.Приемник = СвПр;
ПКС.ИмяИсточника = "Наименование";
ПКС.ИмяПриемника = "Наименование";
ПКС.ТипИсточника = "Строка";
ПКС.ТипПриемника = "Строка";
ПКС.ВидИсточника = "Свойство";
ПКС.ВидПриемника = "Свойство";
ПКС.Наименование = "Наименование --> Наименование";
ПКС.Порядок = 100;
ПКС.Записать;

5. Выгрузить конвертацию в XML

Конв = Справочники.Конвертации.НайтиПоНаименованию("МояКонвертация");
Обр = Обработки.ВыгрузкаКонвертации.Создать;
Обр.КонвертацияДляВыгрузки = Конв;
Обр.ИмяФайлаПравил = "C:\Output\rules.xml";
Обр.СжиматьФайлПравил = Ложь;
Обр.ВыгружатьПравилаКорреспондента = Ложь;
Обр.ВыгружатьПравилаРегистрации = Ложь;
Обр.ВыполнитьВыгрузкуПравил;

Файл = Новый Файл(Обр.ИмяФайлаПравил);
Результат = Новый Структура("ok,path,size", Истина, Обр.ИмяФайлаПравил, Файл.Размер);

Принципы работы

1. Все справочники иерархические "Папки и элементы". ПКО-группы (ЭтоГруппа=true) используются для логической группировки правил внутри конвертации.

2. Владелец = главная связь. ПКО подчинен Конвертации, ПКС/ПКЗ подчинены ПКО, Объекты подчинены Конфигурации, Свойства подчинены Объектам, Значения подчинены Свойствам.

3. Денормализованные дубликаты. Поля типа ИмяИсточника/ТипИсточника в ПКО и ПКС - строковые копии данных из связанной ссылки (для быстрого поиска без join-ов). Заполняй их явно при создании.

4. Поле Код в Конвертациях и ПКО - это "внутренний идентификатор" (UUID-подобная строка фиксированной длины 40 символов с trailing-пробелами). Используется в итоговом XML как <Ид> и <КодПравилаКонвертации>.

5. Имя файла в ИмяФайлаПравил должно быть путем к существующему каталогу. КаталогВременныхФайлов - надежный способ получить временную папку клиента.

6. Гигиена скриптов. Одноразовые/отладочные BSL-скрипты класть только в tools/_tmp/ рабочего каталога КД и чистить после задачи. Устойчивые операции не копить в одноразовых файлах - брать из references/helpers.md и добавлять новые заготовки туда же.

Ограничения

• Все ключевые методы КД работают через execute_code без явного execution_context (toolkit живет в клиентском контексте 1С, директива #Если Клиент Тогда не блокирует).
• В стандартной конфигурации toolkit-а заблокированы ключевые слова Записать, Удалить, УстановитьПривилегированныйРежим. Для создания правил - отключить защиту в форме toolkit-а.
• Возможны trailing-пробелы в строковых ссылочных полях (Код 40 символов с пробелами). При сравнениях использовать СокрЛП(...).
• Обработка ВыгрузкаКонвертации использует переменную модуля мФормаПрогрессора.Значение - при программном запуске она остается не инициализированной, но падения не происходит.

Связанные скиллы

• 1c-mcp-toolkit - HTTP API к живой ИБ 1С (этот скилл - надстройка поверх него).
• composing-1c-queries - синтаксис языка запросов 1С для execute_query.