kd2-rules-mcp

# kd2-rules-mcp — правила обмена «Конвертации данных 2» через агента MCP-сервер, с которым агент (Claude Code, Cursor и другие MCP-клиенты) читает, собирает, правит и проверяет правила обмена **«Конвертации данных 2»** для 1С — `ПравилаОбмена` формата 2.01, правила регистрации и правила корреспондента — по структурам метаданных двух конфигураций. Без Конфигуратора КД и ручной работы в базе КД. Сервер детерминированный: разбирает выгрузки и правила, предлагает кандидатов сопоставления, пишет XML и проверяет. Что во что конвертировать, решает агент — и показывает решения в отчёте и в диффе. ## Возможности | Что | Как | |---|---| | **Метаданные конфигураций** | Из XML-выгрузки конфигурации и расширений (по имени проекта из `projects.yaml` или по путям) либо из файла MD83Exp. Данные базы не нужны | | **Чтение и запись правил** | Без потерь: импорт → экспорт даёт семантически тот же XML (проверено на 60 реальных макетах правил) | | **Подсказки сопоставления** | Объекты, реквизиты, значения перечислений — по алгоритму автонастройки КД; «примитив → ссылка» автоматически не сопоставляется | | **Правка правил** | Создание, изменение и удаление ПКО, ПКС, ПКЗ, ПВД, ПОД, алгоритмов, запросов, параметров. ПКО сразу с реквизитами по подсказкам. Ссылки на несуществующие правила и объекты отклоняются | | **Правила регистрации** | Сборка из состава плана обмена по ПВД | | **Обратное направление** | Черновик правил корреспондента зеркалированием; обработчики — списком «перенести вручную» | | **Проверки** | Формат (как читает БСП), соответствие обеим конфигурациям, ссылки на алгоритмы, параметры обработчика поиска; синтаксис кода обработчиков (внешним синтакс-чекером); штатная загрузка в базу КД; штатная загрузка правил БСП в песочнице без записи в базу | Все инструменты сервера с параметрами, ответами и кодами ошибок — **[docs/tools.md](docs/tools.md)**. Сокращения (ПКО, ПКС, ПКЗ, ПВД, ПОД, ПРО, БСП, MD83Exp…) и термины сервера — **[docs/glossary.md](docs/glossary.md)**. Для агентов в репозитории есть скиллы в `.claude/skills` — их читают Claude Code, Cursor и OpenCode; в папку проекта 1С их ставит `uv run python scripts/build_packs.py --dest <папка проекта> --client claude` ([установка, шаг 6](docs/INSTALL.md#6-подключить-агента)): - `kd2-rules-build` — порядок построения ПКО → ПКС → ПВД → ПРО и чек-лист проверок; справочники по видам правил (`references/`: ПКО, поиск, ПКС, ПКЗ, ПВД, обработчики, ПРО) — что каждое поле и флаг делает в БСП; - `kd2-exchange-pitfalls` — «грабли» обменов через БСП: симптом → причина → проверка → исправление, с доказательствами по коду БСП (дубли при загрузке, поиск по полям, объекты «только по ссылке»…); - `kd2-install` — установка и подключение сервера агентом, с вопросами человеку и проверкой после каждого шага. ## С чем работает в паре Разбор, правка и проверка правил работают без других серверов. Но код обработчиков агент пишет против конфигураций, и для полного цикла ему нужны MCP-серверы для работы с кодом 1С. Мы используем пакет **MCP-серверов для 1С от comol** — он подключается через `shared_mcp` и `code_mcp` в `projects.yaml`: - **Пакет MCP-серверов для 1С** — [vibecoding1c.ru/mcp_server](https://vibecoding1c.ru/mcp_server): граф и поиск по коду и метаданным конфигурации, синтакс-чекер BSL (им проверяется код обработчиков после `handlers_export`), справка платформы, поиск по БСП, шаблоны кода, ревью кода, UI-тестирование форм (MCP QA). - **Правила и скиллы для агентов в проектах 1С** — [github.com/comol/ai_rules_1c](https://github.com/comol/ai_rules_1c): ставят эти серверы в проект и учат агента ими пользоваться (`.mcp.json` проекта, из которого `setup_local.py` берёт адреса). - **MCP в самой информационной базе** (запросы, фрагменты кода, журнал регистрации на живых данных песочницы) — инструменты [github.com/comol/mcp_designer_tools](https://github.com/comol/mcp_designer_tools) для «Конструктора MCP-серверов для 1С»; в `projects.yaml` — `data_mcp` у базы-песочницы. ## 1. Установка Пошагово, с проверкой после каждого шага и разбором ошибок — **[docs/INSTALL.md](docs/INSTALL.md)**. Поручить установку агенту: «Установи kd2-rules-mcp по https://github.com/egordoronchenko/kd2-rules-mcp/blob/main/.claude/skills/kd2-install/SKILL.md». Ниже — коротко, для тех, кто знаком с Docker и MCP. Нужны Docker, Python 3.12 с [`uv`](https://docs.astral.sh/uv/) и — для необязательных финальных проверок — Windows с платформой 1С 8.3 (см. раздел 4). «Конвертация данных» для работы сервера не нужна. Настройки разделены на файлы (в git — только примеры): | Файл | Что в нём | В git | |---|---|---| | `projects.yaml` (пример — `projects.example.yaml`) | проекты → конфигурации (выгрузка и расширения, пути **от папки проекта**) → базы (роль «песочница»/«боевая», строка соединения); серверы кода проекта; обмены между проектами | нет (в форке команды можно хранить) | | `projects.local.yaml` (пример — `projects.local.example.yaml`) | где на **этой** машине лежит папка каждого проекта (любые диски), адрес сервера, путь к платформе 1С, логины баз (`logins`) | нет, у каждого свой | | `.dev.env` проектов 1С | логин базы (`IB_USER`, `IB_PASSWORD`), если у базы в `projects.yaml` задан `dev_env` | нет | ```powershell git clone https://github.com/egordoronchenko/kd2-rules-mcp.git cd kd2-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`. Контейнер `kd2_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](docs/architecture.md#8-развёртывание-и-безопасность)). **Правила прямо в репозитории проекта.** Правила, загруженные в базу из файла, живут вне конфигурации — без истории и диффа. Заведите в репозитории проекта папку (например, `ПравилаОбмена\`) и укажите её в `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 kd2-rules-mcp` (streamable HTTP, `/mcp`). ## 2. Что нужно на входе Полная выгрузка базы (данные) **не нужна** — только метаданные конфигураций: | Вход | Когда | Инструмент | |---|---|---| | Проект из `projects.yaml` — XML-выгрузка конфигурации и расширений из его репозитория | исходники в git | `structure_load_project` — по имени проекта | | Произвольная XML-выгрузка по путям | разовая, вне проектов | `structure_load_xml` | | Файл обработки MD83Exp («Выгрузка структуры метаданных» из поставки КД) | исходников нет | `structure_load_md83exp` | Код модулей для обработчиков агент смотрит через серверы кода проектов (или в той же XML-выгрузке): выгрузочные обработчики — против конфигурации-источника, загрузочные — против приёмника. В MD83Exp кода нет. **Если выгрузка изменилась.** Сервер замечает изменение при повторной загрузке — по `Configuration.xml` и `ConfigDumpInfo.xml`, которые Конфигуратор переписывает при каждой выгрузке; неизменённая берётся из кэша за доли секунды. XML правили руками — загрузить с `force: true`. Что обновление сломало в правилах — загрузить новую выгрузку под новым идентификатором, `structure_compare` со старой и `rules_validate` правил против новой. ## 3. Как ставить задачу агенту Пишите обычным языком, называя план обмена, направление и структуры: - **Добавить объект в обмен** > Через kd2-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`. > Найди причину по правилам и коду БСП, предложи минимальную правку. - **Правила регистрации** > Пересобери правила регистрации плана `ОбменЗарплата3Бухгалтерия3` по ПВД его правил обмена, сравни с макетом. - **Обратное направление** > Построй черновик правил корреспондента для ПКО «Сотрудники»; перечисли обработчики для ручного переноса. Агент **не переносит** результат в проект 1С сам — это отдельный шаг по правилам проекта (захват в хранилище, замена `ExchangePlans\<План>\Templates\…\Ext\Template.txt`, обновление базы). ## 4. Проверки перед переносом | Проверка | Как | Хорошо, если | |---|---|---| | Формат, структуры, ссылки на алгоритмы, параметры поиска | `rules_validate` с обеими структурами | нет **новых** замечаний относительно исходных правил | | Синтаксис кода обработчиков | `handlers_export` → внешний синтакс-чекер 1С (MCP) → `handlers_locate` | нет ошибок разбора | | Штатная загрузка в базу КД | `uv run python kdbase\kd_check.py check <файл>` | `ИТОГ OK`, число ПКО/ПВД ожидаемое | | Штатная загрузка правил БСП (без записи в базу) | `uv run python kdbase\bsp_check.py <правила> <правила корреспондента> --plan <план> --project <проект> --base <песочница>`; готовый архив (`rules_pack`, 2 или 3 файла) — `--archive <ZIP>` вместо пары файлов | `ИТОГ OK` | | Живой обмен между песочницами (поиск в приёмнике, дубли) | `uv run python kdbase\exchange_check.py run --plan <план> --source <проект>.<база> --target <проект>.<база> --object <Документ.Имя> --ref <идентификатор> --source-rules <ZIP> --target-rules <ZIP> --query "<запрос>" --expect-rows N` | `ИТОГ OK`, запрос в приёмнике вернул ожидаемое | Что каждая проверка доказывает и чего не доказывает, где запускается и что ей нужно (база КД в `base\`, логины песочниц, серверы данных баз), как читать итог, типичные ложные замечания и все идентификаторы проверок `rules_validate` — **[docs/checks.md](docs/checks.md)**. `bsp_check` и `exchange_check` работают только с базами роли «песочница»; порядок живой проверки и грабли — скилл `kd2-exchange-pitfalls`. ## 5. Если что-то не так | Симптом | Причина и что делать | |---|---| | `structure_not_found` | структура не загружена — в ответе список загруженных; загрузить `structure_load_project` | | `project_config` | ошибка в `projects.yaml` или неизвестный проект/конфигурация/база — текст говорит, что есть | | «Путь серверу не виден» / «Папка проекта не задана» | папка не подключена: добавить проект в `projects.local.yaml`, `setup_local.py`, `docker compose up -d` | | `object_not_found` | опечатка в имени объекта — в ответе `suggestions`; формат `Справочник.Имя` или `СправочникСсылка.Имя` | | `path_outside_workspace` | сохранять можно только в `workspace\` — путь в ответе | | Проекты правил пропали | после перезапуска контейнера открытые проекты теряются; сохраняйте результат `rules_save` ([рабочая папка и проекты правил](docs/workflow.md)) | | Ответ `match_objects` огромный | сузить `text` и `kind` | | «Неверно указан пользователь или пароль» в `bsp_check` | задать логин базы (`logins` или `.dev.env` проекта) | | `exchange_check`: «пустой ответ сервера данных» | в базе нет инструмента `vcexecutecode` у сервера данных — включить его в настройках сервера данных базы | | Агент не видит инструменты | `docker compose ps`; в Claude Code — одобрить сервер (`claude mcp list`) | ## 6. Ограничения - Только КД 2 (`ПравилаОбмена` 2.01). КД 3 / EnterpriseData — будущий отдельный сериализатор. - Код обработчиков пишет агент; синтакс-чекер ловит синтаксис, но не смысл — смысл проверяет только живой обмен в песочницах. - Черновик корреспондента — основа (около двух третей пар совпадает с ручными правилами); обработчики и асимметричные решения — за агентом. ## План развития Задачи — в [Issues](https://github.com/egordoronchenko/kd2-rules-mcp/issues), доска — [kd2-rules-mcp — план развития](https://github.com/users/egordoronchenko/projects/1). Ближайшая веха — «0.2 — работа из проектов 1С»: скиллы и сервер одной установкой, живые правила в git проекта, ZIP для загрузки и смысловой дифф. Что уже сделано по версиям — [CHANGELOG.md](CHANGELOG.md). ## Разработка ```powershell uv sync uv run ruff format; uv run ruff check; uvx pyright uv run pytest ``` Тесты на синтетических данных (`tests/data`) идут всегда. Остальные включаются переменными окружения, без них пропускаются с причиной: | Переменная | Что включает | |---|---| | `KD2_CORPUS_DIRS` | round-trip и проверки на реальных макетах правил: каталоги XML-выгрузок конфигураций с `ExchangePlans`, через `;`. По умолчанию — выгрузки проектов из `projects.yaml` с папками из `projects.local.yaml` | | `KD2_REFERENCE_DIR` | сверки с эталоном формата: XML-выгрузка конфигурации «Конвертация данных» 2.1. По умолчанию — `reference\kd2-cfg`, если есть | | `KD2_DEPLOY_URL` | тесты развёрнутого контейнера (`http://localhost:8060/mcp`) | | `KD2_KDBASE_CHECK=1` | прогон через базу КД (`kdbase`) | Устройство сервера — слои и модули, поток данных, инварианты, границы, развёртывание и безопасность, как добавить инструмент или проверку — **[docs/architecture.md](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](LICENSE). «1С», «1С:Предприятие», «Конвертация данных», БСП — продукты и товарные знаки фирмы «1С»; конфигураций и поставки КД в репозитории нет (в тестовых данных — короткие выдержки формата).