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

[![Проверки](https://github.com/egordoronchenko/kd-rules-mcp/actions/workflows/checks.yml/badge.svg)](https://github.com/egordoronchenko/kd-rules-mcp/actions/workflows/checks.yml)

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

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

## Как это работает

Вы ставите задачу агенту обычным языком: «добавь справочник в обмен», «почему задваиваются контрагенты».
Агент работает с тремя источниками:

- **kd-rules-mcp** — этот сервер. Читает XML-выгрузки конфигураций (данные базы не нужны), разбирает и пишет
  правила, предлагает кандидатов сопоставления и проверяет результат;
- **MCP-серверы 1С** — код и метаданные конфигураций, синтакс-чекер, справка, сервер данных базы-песочницы
  ([с чем работает в паре](docs/features.md#с-чем-работает-в-паре));
- **скиллы** — порядок работы и грабли обменов с доказательствами по коду БСП.

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

Так выглядит проверка после того, как агент добавил справочник в правила (синтетические данные из `tests/data`):

```text
rules_validate: Ошибок: 1, предупреждений: 1
ошибка  structure.pko_missing  ПКО «Номенклатура» / ПКС Владелец
        Нет ПКО для типов СправочникСсылка.Контрагенты: значения этих типов не выгрузятся
        (свойство пропускается) — создайте ПКО или укажите правило конвертации в ПКС
```

Агент создаёт недостающее ПКО, проверка проходит, `rules_diff` показывает, что изменилось. Пример целиком, от
постановки до диффа, и проверка модуля КД 3 — [usage.md, «Как это выглядит»](docs/usage.md#3-как-это-выглядит).

## Возможности

- **Метаданные** — из XML-выгрузки конфигурации и расширений или из файла MD83Exp.
- **КД 2** — чтение и запись правил без потерь, подсказки сопоставления, правка ПКО, ПКС, ПВД и других правил,
  правила регистрации, черновик обратного направления.
- **КД 3** — разбор модуля менеджера обмена, сверка со схемой формата и конфигурацией, доработка типового обмена
  расширением, собственный модуль правил, перенос правил и регистрации с КД 2.
- **Проверки** — от формата и структур до штатной загрузки правил БСП и живого обмена между песочницами;
  боевые базы — никогда.
- **Папка обмена** — агенту видны обе базы обмена сразу.

Подробно — **[docs/features.md](docs/features.md)**.

## Установка

Пошагово, с проверкой после каждого шага и разбором ошибок — **[docs/INSTALL.md](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`](https://docs.astral.sh/uv/); для необязательных финальных проверок — Windows с платформой 1С 8.3
([проверки](docs/checks.md)). «Конвертация данных» для работы сервера не нужна.

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

Выберите выпущенный тег `vX.Y.Z` с образом в [релизах](https://github.com/egordoronchenko/kd-rules-mcp/releases)
и замените `X.Y.Z` в командах. Между первой и второй командой скопируйте примеры в `projects.yaml` и
`projects.local.yaml`, заполните свои проекты и **абсолютные пути на вашей машине**:

```powershell
'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
```

Скиллы — `kd-rules-mcp-skills-claude-X.Y.Z.zip` (Claude Code, Cursor, OpenCode) или
`kd-rules-mcp-skills-agents-X.Y.Z.zip` (Codex) из того же релиза. Команды для sh и cmd, проверка без клона и
откат — [INSTALL, готовый образ](docs/INSTALL.md#готовый-образ-без-клона).

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

```powershell
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
```

Дальше — запустить `claude` в папке репозитория и одобрить серверы из `.mcp.json` (проверка — `claude mcp list`)
или включить серверы в настройках MCP Cursor. Что в каких файлах настроек, сервер для команды (`bind`, `token`),
своё расширение и правила в репозитории проекта — [INSTALL, установка из исходников](docs/INSTALL.md#установка-из-исходников-альтернатива).

### В папку проекта 1С и папку обмена

Скиллы и подключение сервера в папку проекта 1С:

```powershell
uv run python scripts/build_packs.py --dest <папка проекта> --client claude
```

Папка обмена — отдельная папка вне папок проектов баз, из которой агенту видны серверы обеих сторон:

```powershell
uv run python scripts/build_packs.py --dest <папка обмена> --side bp=<папка проекта БП> --side do=<папка проекта ДО>
```

Зачем она и что внутри — [возможности, папка обмена](docs/features.md#папка-обмена-агент-видит-обе-базы); шаги и
проверка — [INSTALL, папка обмена](docs/INSTALL.md#папка-обмена-правите-обмен-двух-баз).

### Переход с kd2-rules-mcp

Проект переименован в `kd-rules-mcp`. Если сервер уже стоял:

```powershell
git pull
uv sync
uv run python scripts/setup_local.py
docker compose up -d --build
```

Затем в проектах 1С — снова `scripts/build_packs.py --dest <папка> --client claude`. Имена инструментов MCP,
идентификаторы проверок, коды ошибок и переменные окружения `KD2_*` не менялись. Подробно —
[INSTALL, переход с kd2-rules-mcp](docs/INSTALL.md#переход-с-kd2-rules-mcp).

## Документация

| Что | Где |
|---|---|
| Возможности подробно: КД 2, КД 3, скиллы, папка обмена, с чем работает в паре | [docs/features.md](docs/features.md) |
| Установка пошагово, обновление, откат | [docs/INSTALL.md](docs/INSTALL.md) |
| Что нужно на входе, как ставить задачу агенту, ограничения | [docs/usage.md](docs/usage.md) |
| Проверки перед переносом: команды, что доказывают, ложные замечания | [docs/checks.md](docs/checks.md) |
| Рабочая папка, проекты правил, правила в репозитории проекта | [docs/workflow.md](docs/workflow.md) |
| Если что-то не так | [docs/troubleshooting.md](docs/troubleshooting.md) |
| Инструменты сервера: параметры, ответы, коды ошибок | [docs/tools.md](docs/tools.md) |
| Словарь: ПКО, ПКС, ПВД, БСП, MD83Exp и термины сервера | [docs/glossary.md](docs/glossary.md) |
| Устройство сервера | [docs/architecture.md](docs/architecture.md) |
| Разработка, тесты, план развития | [docs/development.md](docs/development.md) |
| Что изменилось по версиям | [CHANGELOG.md](CHANGELOG.md) |

## Участие

Ошибки, идеи и жалобы на обмен — в [Issues](https://github.com/egordoronchenko/kd-rules-mcp/issues): для
проблемы с обменом там есть шаблон, что приложить. Pull request не принимаются — разработка идёт в отдельном
репозитории, а этот собирается из него; предложение правки опишите в issue.

## Лицензия

MIT — см. [LICENSE](LICENSE). «1С», «1С:Предприятие», «Конвертация данных», БСП — продукты и товарные знаки
фирмы «1С»; конфигураций и поставки КД в репозитории нет (в тестовых данных — короткие выдержки формата).