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

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

• «Конвертация данных 2» — ПравилаОбмена формата 2.01, правила регистрации и правила корреспондента по структурам метаданных двух конфигураций.

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

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

Возможности

Общее

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

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

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

Для агентов в репозитории есть скиллы в .claude/skills — их читают Claude Code, Cursor и OpenCode; в папку проекта 1С их ставит uv run python scripts/build_packs.py --dest <папка проекта> --client claude (установка, шаг 6):

• kd2-rules-build — порядок построения ПКО → ПКС → ПВД → ПРО и чек-лист проверок; справочники по видам правил (references/: ПКО, поиск, ПКС, ПКЗ, ПВД, обработчики, ПРО) — что каждое поле и флаг делает в БСП;

• kd2-exchange-pitfalls — «грабли» обменов через БСП: симптом → причина → проверка → исправление, с доказательствами по коду БСП (дубли при загрузке, поиск по полям, объекты «только по ссылке»…);

• kd3-rules — обмен через универсальный формат (EnterpriseData, правила КД 3): как разобрать модуль менеджера обмена, проверить связность и свериться со схемой формата, написать собственный модуль и перенести на него правила КД 2 (references/writer.md, registration.md, recipes.md); что БСП делает с правилами — со ссылками на её код; грабли живых обменов (pitfalls.md);

• kd-install — установка и подключение сервера агентом, с вопросами человеку и проверкой после каждого шага.

Related MCP server: 1c-formsserver

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

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

• Пакет MCP-серверов для 1С — vibecoding1c.ru/mcp_server: граф и поиск по коду и метаданным конфигурации, синтакс-чекер BSL (им проверяется код обработчиков после handlers_export), справка платформы, поиск по БСП, шаблоны кода, ревью кода, UI-тестирование форм (MCP QA).

• Правила и скиллы для агентов в проектах 1С — github.com/comol/ai_rules_1c: ставят эти серверы в проект и учат агента ими пользоваться (.mcp.json проекта, из которого setup_local.py берёт адреса).

• MCP в самой информационной базе (запросы, фрагменты кода, журнал регистрации на живых данных песочницы) — инструменты github.com/comol/mcp_designer_tools для «Конструктора MCP-серверов для 1С»; в projects.yaml — data_mcp у базы-песочницы.

1. Установка

Пошагово, с проверкой после каждого шага и разбором ошибок — 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; для необязательных финальных проверок — Windows с платформой 1С 8.3 (см. раздел 4). «Конвертация данных» для работы сервера не нужна.

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

Выберите выпущенный тег vX.Y.Z с образом в релизах. В пустую папку скачайте три файла этого тега: docker-compose.yml, projects.example.yaml, projects.local.example.yaml. В ссылках и командах замените X.Y.Z выбранной версией. Клон, Git и Python/uv не нужны.

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

'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.

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

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

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).

Для доставки в своё расширение у конфигурации добавьте 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. Что нужно на входе

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

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

Что каждая проверка доказывает и чего не доказывает, где запускается и что ей нужно (база КД в base\, логины песочниц, серверы данных баз), как читать итог, типичные ложные замечания и все идентификаторы проверок rules_validate — **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), только в песочницах:

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. Тесты без баз не заменяют живой прогон принимающего.

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

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

• Для КД 3 сервер пишет собственный модуль правил и расширение-надстройку над типовым, но не правит типовой модуль на месте; собственный тип формата (расширение схемы XDTO) не строит — поля без места в формате идут через AdditionalInfo.

• Код обработчиков пишет агент; сервер проверяет его область видимости, сравнения перечислений формата и обязательные свойства, синтакс-чекер — синтаксис; смысл проверяет только живой обмен в песочницах. В переносе 84 правил три дефекта нашлись только обменом.

• Установка расширения и правил регистрации в базу — за человеком (или агентом с доступом к конфигуратору); сервер пишет комплект и инструкцию.

• Черновик корреспондента — основа (около двух третей пар совпадает с ручными правилами); обработчики и асимметричные решения — за агентом.

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

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

Разработка

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) идут всегда. Остальные включаются переменными окружения, без них пропускаются с причиной:

Устройство сервера — слои и модули, поток данных, инварианты, границы, развёртывание и безопасность, как добавить инструмент или проверку — 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. «1С», «1С:Предприятие», «Конвертация данных», БСП — продукты и товарные знаки фирмы «1С»; конфигураций и поставки КД в репозитории нет (в тестовых данных — короткие выдержки формата).