内容
# 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С»; конфигураций и поставки КД в репозитории нет (в тестовых данных — короткие выдержки формата).
连接信息
猜你喜欢
暂无推荐服务器