Skip to main content
Glama
yllld

MCP Revit Families

by yllld

MCP Revit Families

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

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

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

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

Содержание

Related MCP server: revit-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-адаптер заменяет только ранее созданный и помеченный этим мостом габаритный блок; завершающая операция уточняет его собственные детали.

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

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, Git for Windows, pyRevit — releases. Revit, pyRevit и их библиотеки не входят в репозиторий.

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

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

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

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-окружение

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

py -0p
py -3.14 --version

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

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:

pyrevit env
pyrevit clones
pyrevit attached

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

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

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

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

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

$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

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

$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 в конфигурацию Codex, заменив пути. Обычно это %USERPROFILE%\.codex\config.toml; при заданном CODEX_HOME используйте каталог конфигурации оттуда. Существующие секции сохраняйте; повторный блок [mcp_servers.revit2021] не добавляйте.

В примере установлено tool_timeout_sec = 180: операции Revit могут занимать больше стандартного клиентского ожидания. После настройки переподключите сервер или перезапустите клиент. Для этого локального сервера OAuth не нужен. Официальная инструкция OpenAI по MCP.

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

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

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

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

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

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

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

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

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

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

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

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

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

.\.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

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

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

Пример предлагает коробку 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. Подготовьте отдельный запрос записи:

$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:

.\.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 инструмент не редактирует.

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

{
  "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. Неподтверждённые значения, уже находящиеся в корпоративном шаблоне, не очищаются автоматически: их нужно учитывать при проверке готового семейства.

Детализированный 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. Сохраните законно доступную вам копию локально. Генератор проверяет SHA256 конкретной ревизии; другой PDF нельзя подставить без проверки размеров адаптера.

.\.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. Пример вызова второго шага:

.\.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:

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.

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

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

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

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

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

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

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

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

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

.\.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-тест сборки.

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

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, copyright © 2026 yllld. Сторонние компоненты и исходные документы сохраняют собственные права: THIRD_PARTY_NOTICES.md. Корпоративные RFA, Revit DLL, коммерческие предложения и PDF производителей в репозиторий не включены.

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    D
    maintenance
    Enables AI assistants to interact with Autodesk Revit to query project data, manage elements, and execute generated code via the Model Context Protocol. It provides full compatibility with GitHub Copilot and Claude to automate BIM modeling workflows.
    13
    151 npm
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    A pyRevit extension and Python server that enables AI clients to interact with a live Autodesk Revit session through tools for project info, view management, element operations, and schedule management.
    59
    MIT