# 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-и-формулы)
- [Детализированный WOS-8](#детализированный-wos-8)
- [Все MCP-инструменты](#все-mcp-инструменты)
- [Где лежат результаты](#где-лежат-результаты)
- [Ошибки и их исправление](#ошибки-и-их-исправление)
- [Обновление и отключение](#обновление-и-отключение)
- [Проверки для разработчиков](#проверки-для-разработчиков)
- [Структура, ограничения и лицензия](#структура-ограничения-и-лицензия)

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

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

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

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

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

```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. Для работы моста и подготовки фиксированной спецификации WOS-8 они не нужны.

### 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. Сохрани резервную копию и отдельный результат. Проверь габариты, параметры и сохранность коннекторов. При ошибке или тайм-ауте сначала выясни фактическое состояние операции, не повторяй запись автоматически.

Для сложной формы может потребоваться новый адаптер. Наличие Revit API само по себе не означает, что существующий MCP-инструмент уже умеет любой профиль, sweep, вырез или зависимость.

## Учебный пример без 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 кг здесь — только пример формата, не характеристика WOS-8 или другого изделия.** Если существующий `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). Неподтверждённые значения, уже находящиеся в корпоративном шаблоне, не очищаются автоматически: их нужно учитывать при проверке готового семейства.

## Детализированный WOS-8

Адаптер `revit/revit2021/wos_details.py` воспроизводит наружную геометрию **конкретного чертежа Omega Air WOS-8 №3400401 от 12.12.2013**. Использование этого чертежа для REMEZA требует вашего принятия источника. Габариты адаптера **729,9 × 343,7 × 677 мм** отличаются от округлённых каталожных **730 × 343 × 680 мм**.

Чертёж не включён в репозиторий. Исходный внешний файл: [3400401-WOS-8_1JP.pdf](https://pmskk.jp/wp/wp-content/uploads/2020/12/3400401-WOS-8_1JP.pdf). Сохраните законно доступную вам копию локально. Генератор проверяет SHA256 конкретной ревизии; другой PDF нельзя подставить без проверки размеров адаптера.

```powershell
.\.venv\Scripts\python.exe scripts\prepare_wos8.py --drawing C:\BIM\inputs\3400401-WOS-8_1JP.pdf --accept-source
```

`--accept-source` означает, что вы приняли именно этот чертёж как геометрический источник. Команда **не вызывает Revit**, создаёт в `output/wos8` четыре JSON: спецификацию и три запроса dry-run.

Порядок действий в базовом RFA с выбранным типом:

| Шаг | MCP-инструмент | Файл запроса | Результат записи |
|---|---|---|---|
| 1 | `revit_build_equipment_in_active_family` | `envelope.dry-run.json` | Помеченный габаритный блок, обычные A/B/C |
| 2 | `revit_add_family_details` | `detail.dry-run.json` | Замена своего блока на 51 тело и 8 надписей |
| 3 | `revit_add_family_details` | `finish.dry-run.json` | Исправление положения надписей, выемки, контура блока и перемычки; итоговые виды |

**Для каждого шага сначала dry-run, затем отдельный запрос с `dry_run=false` и токеном именно этого dry-run.** Пример вызова второго шага:

```powershell
.\.venv\Scripts\python.exe scripts\call_active_family.py revit_add_family_details output\wos8\detail.dry-run.json --summary
```

Токен детализации находится в `reports/active_family_detail.json`. Для подготовки записи используйте приём из раздела выше, заменив файл запроса, отчёт и имя инструмента. Завершающий шаг использует тот же отчёт; предыдущий токен повторно не используйте.

Адаптер ожидает блок с `logical_id="wos8_overall_envelope"`, A/B/C как обычные TYPE Length без формул и отсутствие ранее созданных WOS-деталей. Обычная вручную нарисованная коробка без метки не подойдёт. Повторное построение поверх готовой детализации запрещено. Начните с базового RFA или резервной копии до детализации.

Финальная модель: **44 выдавливания, 7 FreeForm, 8 надписей**. `d1=264 мм` и `h1=508,491 мм` привязаны к двум основным корпусам. Прочие формы фиксированы: изменение этих параметров не перестраивает всю сборку согласованно. A/B/C обозначают габариты, но не масштабируют детализированное изделие.

Снятые по масштабу размеры и аппроксимации скруглений/опор не являются заводскими допусками. Скрытые каналы, внутренняя начинка, точная резьба и эксплуатационные зазоры не аттестованы. Коннекторы отсутствуют. Полное соответствие LOD350 конкретного проекта требует отдельной проверки. Эти ограничения следует сохранять при передаче модели дальше.

ADSK этот адаптер сохраняет. Для их заполнения используйте отдельный инструмент и подтверждённые характеристики из источника REMEZA.

Адаптер **Airhorse BPM-40A** также входит в исходники, но зависит от своей ранее созданной сборки, меток и размеров. В этой публикации его JSON в `tests/fixtures` предназначены только для тестов; они не являются готовым производственным заданием. Универсальное выполнение Airhorse «из коробки» по этим заглушкам не предусмотрено.

## Все 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` | Специализированные Airhorse/WOS-адаптеры | Только при `dry_run=false` |
| `revit_finish_detail_presentation` | Оформление созданного **Airhorse**-вида | Только при `dry_run=false` |

Последний инструмент не предназначен для WOS-8: у него отдельная завершающая операция `spec.operation="finish_wos8"` через `revit_add_family_details`.

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

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

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

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

**Ориентируйтесь на `backup_path` и `output_path` ответа:** отдельные операции, включая завершающую WOS, хранят резервную копию в своём каталоге результата.

Перед изменениями 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` | Общий построитель не поддерживает эту форму; нужен соответствующий адаптер |
| WOS: `Drawing hash mismatch` / другая ревизия | Подан другой PDF; не подменяйте hash, пока не проверены геометрия и масштаб |
| Старое поведение после правки 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
```

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

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

Первичная геометрия WOS-8 проверялась в живом Revit: 51 тело, 8 надписей, габариты 729,900125 × 343,700 × 677,000 мм, сохранение ADSK/GUID/типов и отсутствие коннекторов. Это результат конкретной модели, а не гарантия для произвольного семейства и не полный flex-тест сборки.

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

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

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

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

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