> 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/kak-polzovatsya.md).

# Как пользоваться

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

Имя подключения — `1c-kd20`. Пока клиент не видит инструменты этого сервера, сеанс начинать не с чего: ответы инструментов нечем заменить.

## Два разных MCP

Их легко смешать, потому что оба называются MCP.

|                     | KD20                                                                               | Расширение MCP в базе 1С                                  |
| ------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------- |
| Где работает        | контейнер или процесс `kd20-mcp`, порт **8009**, адрес `http://127.0.0.1:8009/mcp` | HTTP-сервис внутри информационной базы, обычно `…/hs/mcp` |
| Зачем               | писать и проверять правила обмена                                                  | выполнять код и запросы в этой базе                       |
| Нужен ли для правил | да                                                                                 | нет. Нужен только для проверок в копии базы               |

У расширения OneAPA сервис называется `APA_MCP`, корневой URL — `mcp`. Рабочий адрес — `http://<публикация>/hs/mcp/tools`. Запрос ровно в `/hs/mcp` зависает: шаблон URL сервиса `/*`, пустой хвост ему не подходит. Ответ живого сервиса — JSON с `serverInfo.name` `APA_MCP_Server_1C`.

У типовой базы с «Конструктором MCP-серверов 1С» тот же адрес `…/hs/mcp`, а инструмент, которым пользуется KD20, — `vcexecutecode`.

`list_metadata` KD20 HTTP-сервисы не показывает. Сервиса нет в снимке конфигурации — это не доказательство, что его нет в выгрузке. Смотрите `HTTPServices` в выгрузке и ответ публикации.

## Что подготовить

1. Выгрузка источника и выгрузка приёмника: файлы Конфигуратора (`Configuration.xml`) или проект EDT (`Configuration.mdo`).
2. Для доработки готовых правил — макет `ExchangePlans\<План>\Templates\ПравилаОбмена\Ext\Template.txt` либо `ExchangeRules.xml`.
3. Для обмена через универсальный формат — общий модуль менеджера обмена и пакет XDTO `EnterpriseData_*` в той же выгрузке.
4. Для проверки внутри 1С — копия базы с опубликованным сервером данных. Рабочую базу можно только читать (`check_base_in_1c`, `exchange_plans_in_1c`, `dump_rules_from_1c`). Загрузка правил и пробная регистрация идут в транзакции, которая всегда отменяется, и только если база отмечена как копия.

Платформа 1С, сама «Конвертация данных» и embeddings для записи правил не нужны.

## Новые правила КД 2

Имена ниже — короткие имена, которые вы задаёте сами.

1. `load_configuration` по выгрузке источника и по выгрузке приёмника.
2. `suggest_object_mappings`, затем `suggest_property_mappings`. Сервер возвращает кандидатов с оценкой. Пары, которых нет по имени, он ищет по составу реквизитов.
3. Договоритесь, первая ли это синхронизация баз, в которых данные уже есть. Если да, черновику нужен `sync_by_id=false` или свойства поиска с продолжением поиска. Иначе одинаковые элементы придут второй раз: умолчание КД 2.1 — синхронизация по идентификатору и без полей поиска.
4. `draft_ruleset`. В ответе есть `по_умолчанию` — что сервер проставил сам.
5. `set_object_rule`, `set_property_rule`, `set_export_rule`, `set_value_map` — точечные правки. Код обработчика пишется через `set_conversion_handler`, `set_algorithm`, `set_query`, а не правкой XML руками.
6. `validate_ruleset`. Пока есть ошибки, `generate_rules_xml` файл не пишет. Явный `allow_errors=true` это ограничение снимает.
7. `export_handlers_bsl`, затем проверка модулей SyntaxCheckServer, затем `locate_handler_line` — строка замечания возвращается в правило и строку обработчика.
8. `generate_rules_xml`. Для макета плана обмена — `style="kd"`.
9. `build_registration_rules`, `validate_registration_rules`, `generate_registration_xml`.
10. `pack_rules_zip` — комплект для формы загрузки правил плана обмена.

Обратное направление — `draft_correspondent_ruleset`. Это черновик: обработчики он не переписывает, а возвращает списком.

## Доработка чужого макета

1. `import_rules_xml` макета, `bind_configurations` к двум загруженным конфигурациям.
2. `validate_ruleset` и запомнить исходные замечания.
3. `trace_object` — путь объекта через ПВД, ПКО и ПКС. `search_ruleset_code` и `read_handler` — найти код. `handler_queries` — разобрать запросы в обработчике.
4. Правки инструментами `set_*`. Снова `validate_ruleset`: новых замечаний быть не должно.
5. `diff_rulesets` с исходным макетом, затем `generate_rules_xml(style="kd")`.

Если в базе правила старше макета, `dump_rules_from_1c` снимает то, что реально загружено в регистр `ПравилаДляОбменаДанными`, и `diff_rulesets` сравнивает это с макетом.

## Обмен через универсальный формат (КД 3)

Сервер модуль менеджера читает и проверяет. Писать модуль он не умеет.

1. `ed_open` модуля источника и модуля приёмника, `ed_schema_open` пакета EnterpriseData нужной версии.
2. `ed_validate` по каждому модулю: связность, схема формата, метаданные конфигурации.
3. `ed_trace` по объекту жалобы. У источника направление `Отправка`, у приёмника — `Получение`. Смотрите `первый_разрыв` и вердикт пути: `целый`, `частично`, `разорван`.
4. `ed_pair_validate` — что источник отправляет и приёмник не принимает, и наоборот.

Чистый `ed_validate` не доказывает, что объект доходит. Слои расширений и маршруты версий формата сервер не читает. `ed_trace` и `ed_pair_validate` входят в образ с версии 0.6.0. Если в `tools/list` их нет, подключён образ 0.5.0: остановитесь на `ed_validate` и так и напишите.

Справка по типичным поломкам: `kd20_format_reference`. Разделы `грабли`, `протокол`, `жалобы` — для КД 2, `кд3_грабли` — для универсального формата.

## Две базы в самом сервере

Расположение баз хранит KD20, не файл проекта.

1. `set_base` для каждой базы: `file_path`, либо `server` и `ref`, либо `web_url`; пользователь, платформа, `data_server_url` (адрес `…/hs/mcp`). Признак `sandbox=true` ставится только на копию. На рабочей базе его нет.
2. `set_exchange`: имя, база-источник, база-приёмник, технология `КД2` или `КД3`, планы обмена сторон, имена правил.
3. `check_base_in_1c` по обеим базам. Замечание здесь важнее правил: сервер данных смотрит в другую базу, снимок конфигурации старше базы, план не подключён к БСП, технология плана не совпадает с технологией обмена.
4. `describe_exchanges(имя)` возвращает `шаги` — те же инструменты с уже подставленными аргументами.
5. `base_launch_string` даёт командную строку. Пароль в ответе закрыт маской. Настоящий пароль попадает в строку только с `include_password=true`, и эту строку не копируют в чат, отчёт и коммит.

`check_rules_in_1c` и `check_registration_in_1c` с записью по имени базы выполняются только при `sandbox=true`.

## Расширение подключено, если сходятся три факта

1. В выгрузке расширения или конфигурации есть HTTP-сервис с корневым URL `mcp` (у OneAPA это `APA_MCP`).
2. Публикация (`default.vrd`) указывает на ту информационную базу, которую вы считаете источником или приёмником. Два алиаса Apache могут смотреть в один и тот же каталог: это одна база, а не источник и приёмник.
3. `GET` рабочего адреса сервиса возвращает JSON, а `check_base_in_1c` узнаёт в ответе имя и версию этой конфигурации.

Пока нет второй базы и второй публикации, обмен «источник → приёмник» существует как пара выгрузок и набор правил. Проверить загрузку правил в приёмнике нельзя.

## Когда проверка закончена

| Обмен | Что должно быть на руках                                                                                                                                                                                                                                                                |
| ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| КД 2  | `check_base_in_1c` без замечаний по обеим базам; `validate_ruleset` без ошибок и без новых предупреждений относительно исходного макета; обработчики проверены SyntaxCheck; `validate_registration_rules` без ошибок; `check_rules_in_1c` успешен в копии источника и в копии приёмника |
| КД 3  | общая версия формата у обоих планов; `ed_validate` без новых ошибок `EDE…` на обоих модулях; `ed_trace` объекта жалобы с обеих сторон; `ed_pair_validate` со статусом каждого объекта. Если двух последних инструментов в сеансе нет — это сказано явно                                 |

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

Коды замечаний, грабли и полный список инструментов — на странице [KD20](https://docs.onerpa.ru/mcp-servery-1c/servery/kd20.md).
