# MCP Revit Families

**Локальный MCP-сервер для работы с семействами в Autodesk Revit 2021 через pyRevit.** Помогает AI-ассистенту проверить открытое семейство, подготовить план изменений, создать геометрию и заполнить подтверждённые параметры оборудования.

Работа выполняется в **уже открытом RFA**. Основной сценарий: открыть своё базовое семейство с нужными ADSK-параметрами → передать ассистенту исходники → проверить dry-run → выполнить построение → проверить сохранённую копию.

Это рабочий прототип с ограниченными геометрическими операциями. Он не является универсальным преобразователем «любой PDF → готовое семейство» и не гарантирует LOD350 автоматически. Чтение чертежа и подготовка спецификации выполняются ассистентом/пользователем; мост исполняет явную спецификацию.

**Лицензия:** [MIT](LICENSE). **Платформа:** Windows, Revit 2021, pyRevit 5.1.x. **Подключение:** локальный MCP через STDIO.

## Содержание

- [Что умеет решение](#что-умеет-решение)
- [Как устроено подключение](#как-устроено-подключение)
- [Что установить](#что-установить)
- [Установка по шагам](#установка-по-шагам)
- [Подключение MCP-клиента](#подключение-mcp-клиента)
- [Первые проверки](#первые-проверки)
- [Повседневная работа с ассистентом](#повседневная-работа-с-ассистентом)
- [Учебный пример без PDF](#учебный-пример-без-pdf)
- [Как перейти от dry-run к записи](#как-перейти-от-dry-run-к-записи)
- [Параметры, ADSK и формулы](#параметры-adsk-и-формулы)
- [Универсальная детализация по ТЗ](#универсальная-детализация-по-тз)
- [Все MCP-инструменты](#все-mcp-инструменты)
- [Где лежат результаты](#где-лежат-результаты)
- [Ошибки и их исправление](#ошибки-и-их-исправление)
- [Обновление и отключение](#обновление-и-отключение)
- [Проверки для разработчиков](#проверки-для-разработчиков)
- [Структура, ограничения и лицензия](#структура-ограничения-и-лицензия)

## Что умеет решение

| Возможность | Что реализовано |
|---|---|
| Диагностика | Версия Revit, версии API, pyRevit, процесс, маршруты связи |
| Аудит RFA | Параметры, GUID, формулы, значения по типам, тела, коннекторы |
| Предварительная проверка | Состояние документа, опорные плоскости, система координат |
| Обычные параметры семейства | Создание геометрических TYPE-параметров Length, Angle, YesNo с проверкой назначения |
| Общий построитель | Параметрические коробки и цилиндры вдоль X, заданные положения и несколько типоразмеров |
| Формулы | Новые арифметические зависимости с проверкой единиц, циклов и источника расчёта |
| ADSK/shared | Запись только в существующие параметры при подтверждённом источнике |
| Детализация | Общая спецификация: контуры, выдавливания, вращение, loft, булевы операции и FreeForm |
| Сохранение | Резервная копия, отдельный результат RFA, JSON-отчёт; для детализации — PNG |

**Коннекторы не создаются и не изменяются.** Их пользователь расставляет самостоятельно. Геометрические штуцеры могут присутствовать в модели без MEP-коннекторов.

Существующие ADSK/shared definitions, GUID, формулы и признаки экземпляр/тип не заменяются. Общий построитель не удаляет исходную геометрию. Универсальная детализация может заменить только явно выбранные помеченные формы своего моста, с проверкой зависимостей и сохранности остальных элементов.

## Как устроено подключение

```text
AI-ассистент / MCP-клиент
          │ локальный STDIO
          ▼
CPython: scripts/run_server.py → mcp_server
          │ HTTP только 127.0.0.1, порт определяется автоматически
          ▼
pyRevit Routes → ExternalEvent → Revit API 2021
          │
          ▼
Активное семейство RFA в открытом Revit
```

Здесь два разных Python:

- **CPython** в `.venv` запускает MCP-сервер. В него устанавливается пакет `mcp`.
- **IronPython** внутри pyRevit выполняет Revit API. Устанавливать `mcp` внутрь pyRevit не нужно.

MCP-клиент сам запускает локальный сервер. Постоянное отдельное окно с `run_server.py` не требуется. HTTP-порт pyRevit — внутренний канал моста, **не URL MCP-сервера** для поля Streamable HTTP.

Папка проекта должна быть доступна для чтения и записи под тем же пользователем Windows, который запускает Revit. Репозиторий не содержит API-ключей и сам не обращается к моделям AI. Авторизация и оплата AI-клиента настраиваются отдельно. Результаты чтения RFA передаются MCP-клиенту; использование их облачным ассистентом зависит от выбранного клиента и его настроек.

## Что установить

| Компонент | Требование / проверенная среда |
|---|---|
| Windows | Локальная рабочая станция с установленным Revit |
| Autodesk Revit | **2021**; проверялся 2021.1.10, build 21.1.100.12 |
| RevitAPI / RevitAPIUI | 21.0.0.0; используются библиотеки установленного Revit |
| pyRevit | **5.1.x**; проверялась сборка 5.1.0.25094+1131-wip |
| Движок pyRevit | IronPython 2.7.12 / .NET Framework 4.8 в проверенной среде |
| CPython | 64-bit; SDK требует Python ≥3.10, локально проверен 3.14.3 |
| MCP SDK | `mcp==1.30.0`, закреплён в requirements.txt |
| Git | Для клонирования и обновления; можно скачать ZIP вручную |
| MCP-клиент | С поддержкой локального STDIO на этом Windows-компьютере |

Другие версии Python из допустимого SDK диапазона не считаются проверенными этой публикацией. Revit 2022–2026 и pyRevit 6.x текущий мост не поддерживает: он намеренно проверяет версии. Не заменяйте номер версии в проверке без переноса и испытания API-кода.

Ссылки для установки: [Python](https://www.python.org/downloads/windows/), [Git for Windows](https://git-scm.com/download/win), [pyRevit — releases](https://github.com/pyrevitlabs/pyRevit/releases). Revit, pyRevit и их библиотеки не входят в репозиторий.

## Установка по шагам

### 1. Скачайте репозиторий

Откройте PowerShell. Ниже используется `C:\BIM`; можно выбрать другую локальную папку, в которой у вас есть право записи.

```powershell
New-Item -ItemType Directory -Path C:\BIM -Force
Set-Location C:\BIM
git clone https://github.com/yllld/MCP-Revit-Families.git
Set-Location C:\BIM\MCP-Revit-Families
```

Без Git: GitHub → **Code → Download ZIP**, распакуйте архив, затем перейдите в папку, содержащую этот README и каталоги `scripts`, `core`, `extensions`. Не работайте прямо внутри ZIP.

### 2. Создайте Python-окружение

Проверьте установленную версию:

```powershell
py -0p
py -3.14 --version
```

Создайте окружение и установите зависимости:

```powershell
py -3.14 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
```

Если используете другую совместимую версию, замените `-3.14` на её номер. Если команды `py` нет, используйте полный путь к установленному `python.exe`. Активировать окружение не обязательно: далее везде указан его собственный интерпретатор.

`requirements-lock.txt` — снимок зависимостей проверенной Windows-среды с Python 3.14.3. Для воспроизведения именно этой среды вместо последней команды можно использовать `pip install -r requirements-lock.txt`. Это не универсальный lock-файл для всех платформ и версий Python.

`requirements-pdf.txt` содержит необязательные инструменты чтения PDF. Для работы моста и выполнения готовых JSON-спецификаций они не нужны.

### 3. Подключите pyRevit к Revit 2021

Если вкладка pyRevit уже есть в Revit 2021, проверьте её версию. Если pyRevit ещё не установлен, установите подходящую сборку 5.1.x и привяжите её к Revit **2021**.

Диагностика из PowerShell:

```powershell
pyrevit env
pyrevit clones
pyrevit attached
```

При необходимости привязки закройте Revit и используйте имя установленного клона из `pyrevit clones`:

```powershell
pyrevit attach ИМЯ_ВАШЕГО_КЛОНА default 2021
```

Это шаблон команды: замените имя клона. Проверьте выбранный движок в выводе `pyrevit env`. Не используйте `--installed`, если хотите подключить только Revit 2021. Если CLI `pyrevit` не найден, проверьте установку CLI и PATH, затем откройте новое окно PowerShell.

### 4. Зарегистрируйте расширение MCP

Из корня репозитория:

```powershell
$mcpRepo = (Get-Location).Path
pyrevit extensions paths add (Join-Path $mcpRepo 'extensions')
```

Добавлять нужно каталог **`extensions`**, а не вложенный `MCPHealth.extension`. Альтернатива через интерфейс: pyRevit → Settings → список каталогов пользовательских расширений → добавить полный путь к `extensions`.

Сохраняйте расположение расширения внутри репозитория: `startup.py` находит соседние модули по относительному пути. Копирование только `MCPHealth.extension` отдельно от остальных каталогов нарушит подключение.

Запустите Revit 2021 заново или выполните pyRevit → Reload при отсутствии выполняемой операции. Должна появиться вкладка **MCP**, панель **Diagnostics**, кнопка **Health** / **Health Check**.

Если ранее было установлено это же расширение из другой папки, оставьте зарегистрированной одну копию. Две копии с одинаковыми маршрутами могут обращаться к разным каталогам `.runtime`.

### 5. Нажмите Health в Revit

Кнопка выводит диагностику. Ожидается `success: true`, версия Revit `2021`, API `21.0.0.0`, `routes_available: true` и список маршрутов `/family-mcp/active/...`.

В корне репозитория появится `.runtime/revit2021-<PID>.json`. Он содержит адрес локального сервера и ID процесса Revit. Это служебный файл, а не постоянная настройка: порт и PID могут измениться после перезапуска.

Для Health открытый документ не обязателен. Для остальных операций откройте **RFA в редакторе семейства**. Открытый RVT с размещённым оборудованием не подходит.

## Подключение MCP-клиента

### Codex

Из корня репозитория:

```powershell
$mcpRepo = (Get-Location).Path
codex mcp add revit2021 -- (Join-Path $mcpRepo '.venv\Scripts\python.exe') (Join-Path $mcpRepo 'scripts\run_server.py')
codex mcp list
```

Либо добавьте секцию из [config/codex.example.toml](config/codex.example.toml) в конфигурацию Codex, заменив пути. Обычно это `%USERPROFILE%\.codex\config.toml`; при заданном `CODEX_HOME` используйте каталог конфигурации оттуда. Существующие секции сохраняйте; повторный блок `[mcp_servers.revit2021]` не добавляйте.

В примере установлено `tool_timeout_sec = 180`: операции Revit могут занимать больше стандартного клиентского ожидания. После настройки переподключите сервер или перезапустите клиент. Для этого локального сервера OAuth не нужен. [Официальная инструкция OpenAI по MCP](https://developers.openai.com/codex/mcp/).

Для одновременной регистрации расширения и сервера есть вспомогательный скрипт:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\register.ps1
```

Он добавляет путь расширения, регистрирует сервер `revit2021` и сохраняет имеющиеся конфигурационные файлы в `.runtime/backups`. Он не устанавливает Revit, pyRevit или Python. Для регистрации только расширения используйте `-SkipCodex`. Параметр `ExecutionPolicy Bypass` действует на запускаемый процесс, а не меняет системную политику навсегда.

### Другие локальные MCP-клиенты

Используйте тип транспорта **STDIO**:

| Поле | Пример |
|---|---|
| Name | `revit2021` |
| Command | `C:\BIM\MCP-Revit-Families\.venv\Scripts\python.exe` |
| Arguments | `C:\BIM\MCP-Revit-Families\scripts\run_server.py` — один аргумент |
| Working directory | Не обязателен; launcher вычисляет корень сам |
| Timeout | 180 секунд, если клиент позволяет настроить |

Для клиентов с форматом `mcpServers` есть [config/mcp.example.json](config/mcp.example.json). Способ импорта зависит от конкретного клиента. В JSON обратные слеши удваиваются, в интерфейсном поле пути — нет. Не добавляйте кавычки как часть самого значения пути.

Обычный облачный чат без доступа к локальному MCP не сможет запустить этот процесс на вашем компьютере. Этот проект не разворачивает публичный HTTP-сервис или туннель.

## Первые проверки

### Проверка MCP без запущенного Revit

```powershell
.\.venv\Scripts\python.exe scripts\check_mcp.py
```

Команда выполняет настоящий MCP handshake и получает список девяти инструментов. Ожидается `success: true`, `revit_contacted: false`. Эта проверка подтверждает работоспособность Python/MCP, но ещё не связь с Revit.

### Проверка связи с Revit

Запустите Revit 2021, нажмите Health, затем:

```powershell
.\.venv\Scripts\python.exe scripts\smoke_mcp.py
```

Ожидается успешный Health через цепочку MCP → pyRevit → Revit. Результат появится в `reports/health_check.json`. Команда не изменяет семейство.

### Проверка активного семейства

Откройте предназначенное для работы `.rfa`, затем:

```powershell
.\.venv\Scripts\python.exe scripts\call_active_family.py revit_get_active_family_context
.\.venv\Scripts\python.exe scripts\call_active_family.py revit_inspect_active_family
.\.venv\Scripts\python.exe scripts\call_active_family.py revit_family_preflight --summary
```

Проверьте имя/путь документа, категорию, текущий тип и сообщения `errors`/`warnings`. Эти команды читают документ. Если тип отсутствует, создайте именованный тип в «Типоразмеры в семействе» либо подготовьте явный каталог типов; обычный пример ниже предполагает текущий тип.

## Повседневная работа с ассистентом

1. Откройте базовое RFA с нужной категорией и корпоративными параметрами.
2. Попросите выполнить Health и аудит. Убедитесь, что ассистент видит нужный файл.
3. Передайте PDF/каталог и точную модель, страницу, строку таблицы или цвет выделения. Дайте клиенту доступ к локальным файлам.
4. Попросите dry-run: размеры с источниками, состав геометрии, параметры, формулы, подтверждённые и пропущенные ADSK.
5. Проверьте спорные размеры. Измерение по масштабу и применение чертежа похожей модели должны быть явно согласованы.
6. После согласования попросите выполнить подготовленную спецификацию. Ассистент получает свежий `context_token` и передаёт `dry_run=false`.
7. Проверьте геометрию и отчёт в сохранённом результате. Коннекторы разместите самостоятельно.

Пример первого сообщения:

> Выполни Health и аудит активного семейства Revit 2021. Покажи путь RFA, категорию, типоразмеры, ADSK-параметры и коннекторы. Пока только чтение.

Пример задачи по чертежу:

> Для модели [точное обозначение] изучи файл [полный путь], страницу [номер]. Подготовь dry-run для открытого RFA: геометрия, обычные Family Parameters с буквенными именами, зависимости и подтверждённые ADSK. Коннекторы не трогай. Отдельно перечисли размеры, которых нет в исходнике. Построение пока не выполняй.

Пример перехода к построению:

> Выполни согласованный dry-run в этом RFA. Сохрани резервную копию и отдельный результат. Проверь габариты, параметры и сохранность коннекторов. При ошибке или тайм-ауте сначала выясни фактическое состояние операции, не повторяй запись автоматически.

Сложные формы описывайте общим языком детализации: контуры, выдавливания, вращение, loft и булевы операции. Неподдерживаемую операцию нужно добавить в общий механизм; произвольные sweeps, сетки, сплайны и зависимости пока не реализованы.

## Учебный пример без PDF

Откройте тестовое семейство без объёмной геометрии и с выбранным типом. Выполните:

```powershell
.\.venv\Scripts\python.exe scripts\call_active_family.py revit_build_equipment_in_active_family examples\box.dry-run.json --summary
```

[Пример](examples/box.dry-run.json) предлагает коробку **800 × 600 × 1200 мм** с обычными TYPE-параметрами `L`, `B`, `H`. Это синтетические учебные размеры; ADSK не заполняются. Коробка центрирована по X/Y, низ — на Z=0. При `dry_run=true` геометрия не создаётся.

Если семейство уже содержит геометрию, пример остановится. Флаг `allow_add_to_existing_geometry=true` разрешает добавление после проверки состава семейства; он не означает разрешение удалить старые тела.

`examples/parameter_policy_preview.json` — отдельный пример политики: синтетическое значение ADSK должно быть пропущено даже при `confidence=1.0`. Это не паспорт оборудования.

## Как перейти от dry-run к записи

`dry-run` — предварительный расчёт плана без изменения модели. `context_token` — отпечаток проверенного состояния документа, **не пароль и не API-ключ**. Его нельзя брать из примера или старого запуска.

После успешного dry-run учебного построения полный ответ хранится в `reports/active_family_build.json`. Подготовьте отдельный запрос записи:

```powershell
$dryReport = Get-Content .\reports\active_family_build.json -Raw -Encoding UTF8 | ConvertFrom-Json
if (-not $dryReport.ready -or $dryReport.errors.Count -gt 0) { throw 'Dry-run contains errors' }
$buildRequest = Get-Content .\examples\box.dry-run.json -Raw -Encoding UTF8 | ConvertFrom-Json
$buildRequest.dry_run = $false
$buildRequest | Add-Member -NotePropertyName context_token -NotePropertyValue $dryReport.context_token -Force
New-Item -ItemType Directory -Path .\output -Force | Out-Null
$buildRequest | ConvertTo-Json -Depth 100 | Set-Content .\output\box.write.json -Encoding UTF8
```

Этот блок только создаёт JSON. Следующая команда **реально изменяет активное RFA**:

```powershell
.\.venv\Scripts\python.exe scripts\call_active_family.py revit_build_equipment_in_active_family output\box.write.json --summary
```

Между dry-run и записью не переключайте документ и не меняйте проверяемые параметры/типы. При `Stale ... context` повторите dry-run и заново сформируйте запрос. Токен не является полным снимком всех возможных свойств Revit и не заменяет проверку активного документа.

Проверяйте результат по полям:

| Поле | Значение |
|---|---|
| `success` | Итог выполнения операции |
| `ready` | Предварительный план допускает выполнение |
| `errors`, `warnings` | Ошибки и ограничения |
| `model_committed` | Изменения уже зафиксированы в документе |
| `saved` | Итоговый файл сохранён |
| `output_path`, `backup_path` | Фактические пути результата и резервной копии |
| `transaction_group_rolled_back` / `rolled_back` | Откат до фиксации; имя зависит от операции |

Не ориентируйтесь только на HTTP 200, отсутствие исключения или `success=true` в dry-run. При `model_committed=true` и `saved=false` геометрия уже существует в открытом документе: повторный build может создать конфликт. Сначала сохраните/проверьте текущий результат.

## Параметры, ADSK и формулы

Для геометрии создаются **обычные Family Parameters**, без shared definitions и ADSK GUID. Предпочтительные имена: `L/B/H`, `l1/b1/h1`, `d1/r1/t1`, `x1/y1/z1`. Если чертёж использует `A/B/C`, сохраняются исходные обозначения через `source.designation`.

Новые формулы требуют `source_type="derived"` и `source.calculation`, совпадающего с выражением. Поддерживаются `+`, `-`, `*`, `/`, скобки, зависимости между объявленными параметрами, размерные литералы вроде `645 mm`. Например, `r1 = d1 / 2`. `if`, `sin`, произвольный Python-код и замена существующих формул не поддерживаются.

Для ADSK/shared одновременно нужны:

- существующий параметр с подходящим типом данных и доступом на запись;
- прямой источник `source_type="direct"`, ссылка `file`/`reference`, поле `field`/`designation`;
- подтверждение нужной модели `model_match=true` и происхождение `origin`;
- достоверность `confidence >= 0.95`, отсутствие конфликтов;
- явные единицы для физических величин.

`0.70 ≤ confidence < 0.95` означает REVIEW; меньшая или отсутствующая оценка — UNKNOWN. Эти значения показываются в плане и не записываются. Число confidence выставляет составитель спецификации: мост проверяет правила, но не доказывает истинность содержимого PDF.

Для внешнего источника нужны `origin="external"` и `search_authorized=true`. Для источника пользователя — `origin="user_provided"`. Значения по масштабу подходят для согласованной геометрии, но не становятся прямыми подтверждёнными характеристиками ADSK.

Если параметр является параметром экземпляра, по умолчанию запись пропускается. Для начальных значений экземпляров **внутри семейства** требуется `write_instance_defaults=true` в `values`-payload инструмента записи либо в `spec` построителя. Запись применяется к существующим типам; признак instance/type не меняется. Размещённые экземпляры в RVT инструмент не редактирует.

Пример структуры запроса записи, который нужно заполнить реальными данными:

```json
{
  "dry_run": true,
  "values": {
    "values": {
      "ADSK_Масса": {
        "value": 184,
        "unit": "kg",
        "confidence": 1.0,
        "source": {
          "source_type": "direct",
          "file": "C:/BIM/inputs/catalog.pdf",
          "page": 3,
          "field": "Масса, строка точной модели",
          "origin": "user_provided",
          "model_match": true
        }
      }
    },
    "parameter_mapping": {"mappings": [], "unmapped": []}
  }
}
```

**184 кг здесь — только пример формата, не характеристика реального изделия.** Если существующий `ADSK_Масса` имеет тип Number, а не Mass, мост не должен угадывать физическую единицу по имени.

Поддерживаемые единицы: Length — `mm`, Angle — `deg`, Mass — `kg`, ElectricalPower — `W/kW`, ElectricalPotential — `V`, Frequency — `Hz`, Flow — `m3/h`/`l/s`, Pressure — `Pa/kPa`; полный список в `core/active_plan.py`. Мост преобразует значения во внутренние единицы Revit.

Подробные правила: [docs/parameter_policy.md](docs/parameter_policy.md). Неподтверждённые значения, уже находящиеся в корпоративном шаблоне, не очищаются автоматически: их нужно учитывать при проверке готового семейства.

## Универсальная детализация по ТЗ

`revit_add_family_details` строит детали по общей JSON-спецификации `schema_version=1`. Название производителя и модель не выбирают код построения: отдельный модуль под изделие не нужен. Формат и примеры всех операций описаны в [docs/universal_details.md](docs/universal_details.md).

| Форма | Как создаётся |
|---|---|
| Корпуса, пластины, патрубки, отверстия в профиле | Выдавливание прямоугольных, круглых, эллиптических, скруглённых или произвольных контуров из линий и дуг |
| Крышки, буртики, тела вращения | Вращение заданного профиля; результат — FreeForm |
| Переходы между сечениями | Loft по последовательности сечений; результат — FreeForm |
| Вырезы и составные формы | Разность, объединение или пересечение явно заданных тел; результат — FreeForm |
| Наклонные детали | Локальная система координат с произвольными ортогональными осями |

Если обычное выдавливание не проходит проверку или фиксацию транзакции, его попытка откатывается, затем мост строит **тот же контур** через FreeForm. Если и это невозможно, откатывается вся операция детализации. Незаметно заменить сложный элемент коробкой или пропустить его мост не должен.

### Как получать модель, близкую к исходнику

1. Дайте ассистенту ТЗ, точную модель оборудования, чертежи с несколькими проекциями и таблицу характеристик. Укажите начало координат и требуемые элементы: корпуса, опоры, крышки, крепления, выступы, геометрические штуцеры, отверстия и зоны сопряжения.
2. Ассистент составляет перечень требований `requirements` и связывает каждое с деталями. Мост проверяет эти связи. Полноту самого перечня относительно PDF проверяет ассистент/пользователь: мост не читает чертёж самостоятельно.
3. Явные размеры переносятся напрямую. Размеры по масштабу отмечаются `accuracy="scaled"`, с проекцией, страницей, калибровкой, расчётом и оценкой погрешности. Для них требуется `accept_scaled_dimensions=true`, основанный на разрешении пользователя. Предположения разрешаются отдельно через `accept_assumptions=true` и всегда остаются отмеченными.
4. Выполните dry-run. В нём видны все детали, формы, источники, замены, предупреждения, ожидаемые габариты и допуск проверки. Ошибки или непокрытые требования блокируют запись.
5. Выполните запись с актуальным `context_token`. Мост проверяет сохранность семейства, число новых форм, габариты всей сборки и, если заданы, границы каждой детали. При ошибке до фиксации откатывается вся группа транзакций.
6. Сверьте сохранённые виды **3D, спереди, справа и сверху** с исходником: контуры, взаимное положение, отверстия, выступы и монтажные интерфейсы. Совпадение габаритной коробки не доказывает совпадения формы. Корректировки передаются тем же форматом JSON.

Для изменений можно явно указать `replace_generated_ids`: заменяются только выбранные формы с меткой нашего моста. Повторный запуск поверх тех же ID без такого списка запрещён. Удаление зависимых размеров или других защищённых элементов вызывает откат; в этом случае начните с чистого базового RFA. Непомеченную исходную геометрию инструмент не заменяет.

**Параметризация:** новый общий механизм детализации создаёт фиксированную геометрию, общую для типов семейства. Он не добавляет параметры и не привязывает FreeForm к размерам. Для параметрической основы и обычных буквенных параметров используйте `revit_build_equipment_in_active_family`; ADSK заполняйте отдельным инструментом только по подтверждённым данным. Изменение L/B/H не перестраивает статические детали — нужна новая спецификация и повторная детализация. Это ограничение явно присутствует в dry-run.

### Учебный запуск

Откройте отдельное тестовое базовое RFA без объёмной геометрии, с выбранным типом. Пример описывает условную сборку **100 × 60 × 100 мм** из четырёх деталей: основание с отверстиями, цилиндр, буртик вращения и переход. Он не относится к реальному изделию.

```powershell
.\.venv\Scripts\python.exe scripts\call_active_family.py revit_add_family_details examples\details.dry-run.json --summary
```

Отчёт: `reports/active_family_detail.json`. Для записи используйте порядок из раздела [Как перейти от dry-run к записи](#как-перейти-от-dry-run-к-записи), подставив этот файл примера, этот отчёт и инструмент `revit_add_family_details`. Результат: отдельный `Detailed_Family.rfa`, JSON-отчёт и четыре PNG. Если экспорт PNG не удался, в ответе будет предупреждение; визуальная проверка всё равно нужна.

### Задание ассистенту

> Построй семейство в активном базовом RFA максимально близко к приложенному ТЗ. Используй универсальную детализацию schema_version=1 без модулей под конкретное изделие. Сначала перечисли все требуемые элементы и составь dry-run. Явные размеры возьми с чертежа; недостающие видимые размеры разрешаю снять по масштабу ортогональных проекций, с калибровкой и указанием погрешности. Предположения не подставляй молча. Используй выдавливания; сложные формы создавай FreeForm через вращение, loft или булевы операции. Не упрощай и не пропускай неподдерживаемую форму без согласования. После построения сравни габариты и четыре вида с исходником, перечисли отклонения и исправь их тем же общим механизмом. Коннекторы не создавай и не меняй. ADSK заполняй только по достоверным прямым данным.

**Предел точности:** гарантировать «всегда 1 в 1» по любому PDF нельзя. Скрытая геометрия, нечитаемые размеры, перспективные изображения и неподдерживаемые формы требуют дополнительных данных или согласованного упрощения. Мост не присваивает LOD350 автоматически: готовность определяется требованиями конкретного ТЗ и проверкой результата. Новые операции должны расширять общий язык геометрии, а не добавлять ветвления по марке изделия.

**Обновление:** прежние запросы с `profile`/`operation` и отдельные генераторы под оборудование удалены. Старые JSON нужно перевести в общий формат; существующие RFA автоматически не переделываются. Перезапустите Revit и MCP-клиент после обновления кода.

## Все MCP-инструменты

| Имя | Назначение | Изменение RFA |
|---|---|---|
| `revit_health_check` | Связь, версии, PID, Routes | Нет |
| `revit_get_active_family_context` | Активное семейство и контекст | Нет |
| `revit_inspect_active_family` | Полный аудит | Нет |
| `revit_family_preflight` | Аудит перед построением, плоскости и координаты | Нет |
| `revit_set_existing_family_parameters` | Существующие параметры с источником | Только при `dry_run=false` |
| `revit_build_equipment_in_active_family` | Коробки, цилиндры X, обычные параметры и типы | Только при `dry_run=false` |
| `revit_test_geometry_in_active_family` | Тестовая коробка и три flex-сценария | Только при `dry_run=false` |
| `revit_add_family_details` | Универсальная детализация по явной спецификации | Только при `dry_run=false` |
| `revit_finish_detail_presentation` | Оформление активного помеченного MCP-вида детализации | Только при `dry_run=false` |

Оформление доступно для любого вида, созданного универсальной детализацией; имя изделия не проверяется.

Тест геометрии создаёт три служебных `MCP_*` параметра только для интеграционной проверки и проверяет размеры 800×600×1200 → 1000×800×1500 → 600×400×900 мм. Это исключение для теста, а не система имён производственных семейств. Запускайте запись теста в тестовом RFA.

## Где лежат результаты

Все пути считаются от корня вашего клона репозитория:

| Каталог | Содержимое |
|---|---|
| `.runtime/` | Адреса запущенных Revit-процессов и резервные копии настроек |
| `reports/` | Последние JSON-ответы по операциям; следующий запуск может их заменить |
| `backup/<UUID>/` | Резервные копии перед изменениями |
| `tests/output/<UUID>/` | Результат RFA, подробный JSON и PNG конкретного запуска |
| `inputs/` | Ваши исходники, если вы выбрали хранить их здесь |

**Ориентируйтесь на `backup_path` и `output_path` ответа.** Папки запусков разделены UUID.

Перед изменениями SaveAs сохраняет текущее состояние, включая несохранённые правки. Активный документ получает путь резервной копии, затем — результата. Старый исходный файл на диске не перезаписывается. При неудаче до фиксации транзакций документ может остаться открытым под именем резервной копии. После фиксации ошибка сохранения или экспорта не означает автоматический откат геометрии.

Перечисленные рабочие каталоги, PDF, RFA, DLL и конфигурации сессий исключены из Git. `.gitignore` не является средством шифрования: не публикуйте диагностические отчёты без проверки путей, названий и содержимого параметров.

## Ошибки и их исправление

| Сообщение / симптом | Что проверить |
|---|---|
| `No Revit 2021 endpoint` | Загружено ли расширение; нажмите Health; есть ли `.runtime/revit2021-*.json` в том же клоне, из которого запускается MCP |
| Нет вкладки MCP | Путь к `extensions`, версия/привязка pyRevit, ошибки запуска; после установки перезапустите Revit |
| `No module named mcp` | Клиент должен запускать `.venv\Scripts\python.exe`; установите requirements именно этим интерпретатором |
| `No module named core` / `revit.revit2021` | Не перенесён ли один каталог `.extension` отдельно; сохранена ли структура репозитория |
| `Expected pyRevit 5.1.x` | Установлена неподдерживаемая версия pyRevit; обновление до любой последней версии не является исправлением |
| `Open the intended RFA manually` | Активен RVT, начальный экран или другой документ; откройте нужное семейство в редакторе |
| `Multiple Revit 2021 instances` | Закройте лишний процесс или задайте `REVIT_PROCESS_ID` |
| `Stale ... context` | Повторите dry-run после переключения документа/изменения параметров; используйте новый токен |
| `Generated logical_id already exists` | Эта геометрия уже построена; проверьте текущее состояние, не удаляйте метки для обхода защиты |
| Параметр попал в REVIEW/UNKNOWN | Недостаточно достоверности или прямого источника; дополните исходные данные |
| `instance_default_requires_opt_in` | Требуется явный `write_instance_defaults=true`, если вы действительно меняете defaults экземпляров |
| Ошибка единиц / типа параметра | Проверьте фактический ParameterType и unit, а не только имя ADSK |
| `Unsupported primitive` | Выберите поддерживаемую общую операцию детализации; неизвестные формы не подменяются упрощёнными |
| `Source drawing changed` | PDF изменился; проверьте ревизию, размеры и масштаб перед обновлением SHA256 |
| Старое поведение после правки Revit-кода | Завершите запрос, затем MCP → Diagnostics → Health; если требуется, перезапустите Revit |
| Клиент не видит новые инструменты | После изменения MCP-сервера переподключите его / перезапустите клиент |
| Сервер запущен вручную и «ничего не пишет» | STDIO ждёт MCP-протокол; используйте `check_mcp.py` или клиент, а не браузер |
| Timeout / `outcome may be unknown` | Проверьте диалоги Revit, активный документ, `reports` и папку запуска; не отправляйте повторную запись до выяснения результата |

При нескольких Revit для текущего окна PowerShell:

```powershell
Get-Process Revit | Select-Object Id, MainWindowTitle
$env:REVIT_PROCESS_ID = '12345'
.\.venv\Scripts\python.exe scripts\smoke_mcp.py
```

Замените `12345` на реальный PID. Для запуска из MCP-клиента задайте переменную в конфигурации сервера: `[mcp_servers.revit2021.env]` для Codex, объект `env` для соответствующего JSON-клиента. PID меняется при перезапуске Revit.

Не запускайте несколько записей одновременно. Блокировка моста действует внутри одного процесса MCP; несколько отдельных клиентов могут обойти её. Перед вызовом завершите редактирование эскиза, закройте модальные окна и дождитесь окончания текущей операции Revit.

Мост использует loopback, без аутентификации маршрутов pyRevit. PID и context_token проверяют контекст, но не заменяют контроль доступа. Решение рассчитано на доверенную локальную рабочую станцию: не публикуйте Routes-порт в сеть и не меняйте адрес на `0.0.0.0`.

## Обновление и отключение

Для обновления сначала завершите запросы, сохраните свои изменения кода, затем из корня клона:

```powershell
git pull --ff-only
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
```

Нажмите Health в Revit при отсутствии открытой транзакции. Кнопка обновляет обработчики этого проекта в текущем движке и использует существующий сервер Routes. Для первоначальной загрузки расширения нужен Reload pyRevit или перезапуск Revit. При изменении MCP-схем переподключите MCP-клиент. При переносе папки заново зарегистрируйте путь расширения и пути Python/launcher.

Отключение из корня клона:

```powershell
codex mcp remove revit2021
pyrevit extensions paths forget (Join-Path (Get-Location).Path 'extensions')
```

После этого перезапустите Revit и клиент. Эти команды не удаляют созданные семейства или саму папку проекта. В другом MCP-клиенте удалите соответствующую запись сервера через его настройки.

## Проверки для разработчиков

Из корня репозитория:

```powershell
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe scripts\check_mcp.py
```

Unit-тесты проверяют политику параметров, формулы, единицы, источники, контекст, ограничения транспорта и отсутствие автоматического повтора записи. Проверки детализации включают контуры, источники, калибровку масштаба, покрытие ТЗ, габариты и запрет неявной замены. Тестовые данные находятся в `tests/fixtures` и `examples`, поэтому частные PDF и локальные отчёты для unit-тестов не нужны.

`check_mcp.py` проверяет реальный STDIO handshake и список инструментов без обращения к Revit. `smoke_mcp.py` выполняет живой read-only Health. Успех unit-тестов или компиляции CPython **не доказывает** корректность Revit API/IronPython: изменённые операции дополнительно проверяйте в Revit 2021 на тестовом RFA, включая Regenerate, readback, сохранение и геометрию.


Универсальная детализация этой версии проверена офлайн; полный прогон новых операций в живом Revit 2021 ещё требуется. Для него используйте учебный пример и порядок проверки в [docs/universal_details.md](docs/universal_details.md).

## Структура, ограничения и лицензия

```text
core/                         Независимые от Revit планы, формулы, политика параметров
mcp_server/                   MCP-инструменты и HTTP-мост к pyRevit
revit/revit2021/               Аудит, общий язык геометрии, построение и сохранение
extensions/MCPHealth.extension/  Расширение pyRevit и кнопка Health
scripts/                      Запуск, регистрация и проверки
config/                       Примеры конфигураций и схема mapping
examples/                     Учебные запросы dry-run
tests/                        Unit-тесты и обезличенные регрессионные данные
docs/                         Политика параметров и формат универсальной детализации
```

Сохранены исторические `family_roundtrip.py` и `template_locator.py` с их тестами. Создание нового документа из RFT через них не включено в текущие MCP-инструменты и Routes. Основной сценарий — активное RFA.

Ограничения: нет универсального PDF-парсера, работы с проектами RVT, автоматического создания ADSK, редактирования коннекторов, произвольных sweeps, mesh, сплайнов и параметрических void-форм и автоматической полной параметризации FreeForm. Контроль сохранности исходной геометрии по ID, bounding box и числу тел не является полным сравнением топологии.

Исходный код проекта распространяется по [MIT](LICENSE), copyright © 2026 yllld. Сторонние компоненты и исходные документы сохраняют собственные права: [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). Корпоративные RFA, Revit DLL, коммерческие предложения и PDF производителей в репозиторий не включены.