# 1c-meta — создание и правка метаданных 1С в выгрузке конфигуратора и проекте EDT

Инструмент для ИИ-агентов: создаёт и правит метаданные, формы и код BSL в
выгрузке конфигуратора и в проекте 1C:EDT. Каналов два — командная строка
(CLI) и MCP-сервер, задание у них одно. Инструмент пишет файлы выгрузки так
же, как их пишет конфигуратор, и не даёт нарушить правила, которые иначе
всплывают только при загрузке в базу.

Проверено двумя способами: сборкой обратно (побайтно) всех существующих
объектов выгрузки крупной типовой конфигурации и кругом «записали → загрузили
конфигуратором → выгрузили обратно», в котором платформа не меняет ни символа.

Лицензия — MIT (`LICENSE`); сторонние компоненты — `THIRD_PARTY_NOTICES.md`.

## Оглавление

* [Установка](#установка)
* [Быстрый старт](#быстрый-старт): [командная строка](#командная-строка), [MCP-сервер](#mcp-сервер)
* [Что умеет](#что-умеет)
* [Ограничения](#ограничения)
* [Язык](#язык)
* [Лицензия](#лицензия)
* Справка в `docs/`:
  [запуск из командной строки](docs/cli.md) ·
  [MCP-сервер](docs/mcp.md) ·
  [объекты метаданных](docs/metadata.md) ·
  [формы](docs/forms.md) ·
  [правка кода](docs/code.md) ·
  [проверка правок и сверка плана](docs/verify.md) ·
  [проект EDT](docs/edt.md) ·
  [внешние обработки и отчёты](docs/external.md) ·
  [профиль соглашений](docs/profile.md) ·
  [чего нет](docs/limitations.md) ·
  [устройство и проверки](docs/architecture.md) ·
  [словарь](docs/glossary.md)

## Установка

Нужны Python 3.10 или новее (проверено на 3.13) и git в `PATH`. Пакеты:

```
py -3 -m pip install "lxml>=5.0"     # всегда: разбор и сборка файлов выгрузки
py -3 -m pip install "mcp>=1.29"     # только для MCP-сервера (pydantic придёт с ним)
py -3 -m pip install pytest ruff     # только для проверок
```

На Linux и macOS вместо `py -3` — `python3`. Инструмент запускается из каталога
репозитория как есть; пакетом для `pip install` он не оформлен. `pyproject.toml`
хранит настройки ruff и pytest и метаданные проекта, а установка — как описано
в этом разделе.

**Для проекта 1C:EDT** нужна ещё таблица метамодели EDT — порядок и умолчания
свойств объектов и форм. В репозитории её нет: она снимается с моделей
установленного 1C:EDT, на той машине, где инструмент работает:

```
py -3 tools/edt_model_from_xcore.py     # без аргумента — пул p2: %USERPROFILE%\.p2\pool\plugins
```

Получится `meta/acl/edt_metamodel.py` (в `.gitignore`). Без неё выгрузка
конфигуратора работает полностью, у проекта EDT работают проверки и
нормализация, а запись и показ отклоняются с этой же подсказкой.
Таблицу снимают заново после обновления EDT и после обновления инструмента,
если в нём менялся список моделей скрипта (так, с поддержкой расширения
конфигурации в неё вошли модели расширения).

Выгрузка — каталог, который пишет конфигуратор командой «Конфигурация →
Выгрузить конфигурацию в файлы». Результат загружается обратно командой
«Загрузить конфигурацию из файлов» — целиком, а не частично (раздел
[«Ограничения»](#ограничения)).

## Быстрый старт

### Командная строка

Задание — файл JSON: куда писать (`repo` — каталог выгрузки, где лежит
`Configuration.xml`) и что сделать. Для пробы годится пустая выгрузка: скопируйте
`meta/tests/эталоны/формы/Configuration.xml` в пустой каталог и укажите его
в `repo`. Примеры дальше ссылаются и на типовые объекты (`Справочник.Организации`
и другие) — в пустой выгрузке их нет, и такие ссылки получат `ТИП-НЕТ`, пока
объекты не заведены. Справочник с одним реквизитом:

```json
{"repo": "C:/путь/к/выгрузке/cf",
 "objects": [
   {"вид": "Справочник",
    "поля": {"имя": "мой_Пример", "синоним": "Пример",
             "реквизиты": [
               {"имя": "Комментарий", "синоним": "Комментарий",
                "тип": {"вид": "Строка", "длина": 100}}]}}]}
```

Сохраните его в UTF-8 как `задание.json` и посмотрите, что будет сделано, —
на диск при этом не пишется ничего:

```
py -3 meta/add.py задание.json
```

```
Выгрузка: C:/путь/к/выгрузке/cf
Справочник мой_Пример
   замечаний нет
   синоним: Пример
   реквизиты: Комментарий «Комментарий» (Строка(100))
   (ещё 50 полей не названы в задании — значения по умолчанию; …)

План:
   создать  C:\путь\к\выгрузке\cf\Catalogs\мой_Пример.xml (6150 Б)
   изменить C:\путь\к\выгрузке\cf\Configuration.xml (станет … Б, было … Б)

Просмотр: ничего не записано. Для записи повторите с --apply.
```

План тот — записываем:

```
py -3 meta/add.py задание.json --apply
```

Ключи командной строки — в [docs/cli.md](docs/cli.md).

### MCP-сервер

Второй канал — тот же инструмент для агентов, у которых нет оболочки. Сервер
подключается в настройках MCP-клиента; у Claude Code — файл `.mcp.json` проекта,
ключ `mcpServers`:

```json
{"mcpServers": {
  "1c-meta": {"type": "stdio", "command": "py",
              "args": ["-3", "C:\\путь\\к\\1c-meta\\meta\\mcp_server.py"],
              "env": {"META_ROOTS": "C:\\путь\\к\\проекту1\\cf;C:\\путь\\к\\проекту2\\cf",
                      "META_PROFILE": "C:\\путь\\к\\профиль.json"}}}}
```

`py -3` — запуск Python на Windows; на Linux и macOS — `"command": "python3"`
и путь к `mcp_server.py` без `-3`. Разделитель путей в `META_ROOTS` — «;».

`META_ROOTS` — белый список: сервер работает только с выгрузками из него, и на
чтение, и на запись; без настройки отказ получает любой инструмент с `repo`,
работает только справка `fields`. `META_PROFILE` — путь к профилю соглашений
команды ([docs/profile.md](docs/profile.md)); без профиля соглашения нейтральные.

То же задание принимает MCP-сервер: `metadata_check` — просмотр,
`metadata_apply` — запись (раздел [«MCP-сервер для агентов»](docs/mcp.md):
там все инструменты сервера).

## Что умеет

* **Объекты метаданных** — 15 видов: создать сразу с содержимым (реквизиты,
  табличные части, измерения и ресурсы, права роли), добавить вложенную
  сущность, изменить свойство, удалить с поиском ссылок, переименовать со
  всеми ссылками, завести атомарные роли — [docs/metadata.md](docs/metadata.md).
* **Управляемые формы** — новая или существующая форма: реквизиты, команды,
  элементы пятнадцати видов, обработчики; для типовой формы — код доработки
  вместо правки XML — [docs/forms.md](docs/forms.md).
* **Код BSL вставками** — метки с датой, задачей и автором, комментирование
  заменяемого кода, откат вставок задачи, переименование и перенос метода —
  [docs/code.md](docs/code.md).
* **Проверка правок задачи**, нормализация формата файлов и сверка плана
  изменений с фактом — [docs/verify.md](docs/verify.md).
* **Проект 1C:EDT** и расширение конфигурации — [docs/edt.md](docs/edt.md).
* **Внешние обработки и отчёты** в их собственной выгрузке —
  [docs/external.md](docs/external.md).
* **Профиль соглашений команды** — приставка, метки, атомарные роли, уровни
  правил — [docs/profile.md](docs/profile.md).

Полная таблица операций — в [docs/metadata.md](docs/metadata.md#что-умеет).

## Ограничения

* **Формат выгрузки — 2.21**, то есть платформа 8.5. Выгрузку другого
  формата инструмент читает, но метаданные и формы в неё не пишет (раздел
  [«Запуск»](docs/cli.md)).
* **Загрузка обратно — только полная.** Служебный `ConfigDumpInfo.xml`
  инструмент не правит: его пересобирает платформа при загрузке.
* Заведено 15 видов объектов конфигурации из 43 (и внешние обработка с
  отчётом) и 15 видов элементов форм из 31; чего
  нет, перечислено в разделе [«Чего нет»](docs/limitations.md).
* **Проект EDT** поддерживается наравне с выгрузкой; оговорки — в разделе
  [«Проект EDT»](docs/edt.md).
* **Внешние обработка и отчёт** — в своей выгрузке, без удаления и
  переименования; оговорки — в разделе [«Внешняя обработка и отчёт»](docs/external.md).

## Язык

Русский — в данных и в том, что видит пользователь: имена видов и свойств
метаданных 1С, поля заданий, значения перечислений, коды и тексты находок,
сообщения; комментарии в коде — тоже по-русски. Часть внутренних имён в коде
(функций, классов, переменных) пока русская — это наследие ранних версий, их
переводим на английский; новые имена пишутся по-английски.

## Лицензия

MIT — [LICENSE](LICENSE). Сторонние компоненты и их лицензии —
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).