MCP-сервер RevitAiTools: архитектура, инструменты и безопасность

Что такое MCP-сервер в Revit

MCP (Model Context Protocol) — способ, которым AI-клиент узнаёт о возможностях приложения и вызывает их. Сервер публикует инструменты с именами, описаниями и JSON-схемами аргументов; клиент передаёт список модели, она выбирает вызов, сервер выполняет его и возвращает структурированный результат.

В RevitAiTools сервер живёт не отдельным процессом, а внутри надстройки revitCopilot. Это принципиально: инструментам нужен доступ к живому документу Revit, а Revit API однопоточный. Отдельный процесс пришлось бы соединять с Revit через мост, и каждый вызов проходил бы лишний разрыв. Здесь вызов приходит по HTTP и ставится в очередь на UI-поток Revit.

Результат — не «магия чата», а предсказуемый контракт: если инструмента нет в каталоге, модель не может его вызвать; если аргументы не проходят схему, вызов отбивается до Revit; если инструмент пишет в модель, он делает это в транзакции.

Как выглядит путь запроса

Клиенты, которые работают через stdio, не обращаются к порту напрямую: мост сам находит запущенный экземпляр Revit по port-file, поднимает соединение и проксирует JSON-RPC. Поэтому в конфиге клиента указывается команда моста, а не URL.

Транспорт и авторизация

• Протокол: JSON-RPC 2.0, транспорт: Streamable HTTP, JSON-режим.
• Endpoint: http://127.0.0.1:18765/mcp, health-check: http://127.0.0.1:18765/health.
• Сервер слушает только loopback; удалённого доступа без явного туннеля нет.
• Bearer token обязателен; он создаётся при старте и записывается в port-file экземпляра.
• Таймаут запроса по умолчанию 600 с, максимум 3600 с; лимит 600 запросов/мин.
• SSE-стриминга и batch-запросов нет: один вызов — один ответ.

curl -s http://127.0.0.1:18765/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": { "name": "get_document_info", "arguments": {} }
  }'

Каталог инструментов

В репозитории около 1 400 инструментов в ~180 файлах и 47 категориях. Точные числа в проектной документации расходятся (измерения делались в разное время), поэтому здесь указано округление, а не «ровно N». Один инструмент — одна функция агента: имя в snake_case, описание и JSON-схема аргументов.

Каталог трёхуровневый: сначала категории, затем список инструментов категории, затем схема конкретного инструмента. Это экономит контекст модели — не нужно передавать все схемы сразу. Поиск по каталогу доступен инструментом capability_search_methods.

Контракт вызова

Успешный ответ содержит data. Ошибка — error и errorCode; успех не содержит этих полей. Такой конверт позволяет агенту различать «пустой результат» и «сломалось».

{
  "data": {
    "name": "get_walls",
    "category": "Wall",
    "description": "Get walls from the active document",
    "tier": 1,
    "status": "active",
    "inputSchema": {
      "type": "object",
      "properties": {
        "filter": { "type": "string" },
        "levelId": { "type": "integer" }
      }
    }
  }
}

Схема пишется вручную и проверяется до выполнения. Опечатка в имени аргумента — ошибка вызова, а не молчаливое действие с другим смыслом. Для инструментов записи схема дополняется параметрами политики (см. ниже).

Запись в модель: транзакции и политика

Инструмент объявляет, нужна ли ему транзакция. Хост сам открывает Transaction и коммитит её после успешного выполнения; инструмент не должен открывать свою. Это убирает класс ошибок «забыл Commit» и позволяет одинаково обрабатывать откат при исключении.

• Чтение отделено от записи. Read-only инструменты не требуют транзакции; write-инструменты помечены явно.
• Удаление — с dry-run. delete_elements по умолчанию возвращает план, а не удаляет.
• План записи параметров. parameter_write_plan классифицирует значения, возвращает решения и contextToken, не меняя модель.
• Порог уверенности. 0.95 и выше — CONFIRMED, 0.70 и выше — REVIEW; ниже — UNKNOWN. Запись REVIEW требует явного acceptReview.
• Политика. off | warn | enforce; по умолчанию off. В enforce жёстко отбиваются конфликт источника, несовпадение единиц, read-only/формульные параметры, отсутствие происхождения значения и устаревший контекст.
• Размер пакета. От 1 до 200 значений за вызов.

Отдельно важно: transaction_rollback не отменяет уже закоммиченные write-инструменты. Если нужен откат, его планируют до записи, а не после. Это ограничение архитектуры, а не недосмотр.

Что сервер не делает

• Нет SSE-стриминга и batch-запросов: один ответ — один JSON-RPC результат.
• Сервер слушает только loopback и требует Bearer token; удалённого доступа без туннеля нет.
• stdio-мост работает с активным документом; два документа с одинаковым именем неразличимы.
• capability_get_method_info.status всегда возвращает active — по нему нельзя понять, что инструмент сломан.
• Офлайн-каталога инструментов нет: список доступен только у запущенного Revit.
• transaction_rollback не отменяет уже закоммиченные write-инструменты.
• Координаты — в футах, кроме create_level, который принимает миллиметры.
• Часть модулей (PipeConnect, ExplosionScheme, DynamicUpdater) сохраняет кнопки ленты и не полностью headless.

Эти ограничения — часть контракта. Если задача требует неактивного документа, потоковой передачи или гарантированного отката после коммита, её нельзя решить «настройкой»: нужен другой сценарий.

Как подключить

1. Запустить Revit поддерживаемой версии и убедиться, что плагин загрузился.
2. Зарегистрировать stdio-мост в клиенте (`setup-mcp-bridge.ps1` или конфиг вручную).
3. Проверить соединение и список инструментов в клиенте.
4. Первый запрос — read-only: `get_document_info` или выборка стен.
5. Запись — только после плана и на копии модели.

Пошаговая настройка Claude Code — в отдельной инструкции; версии и клиенты — на странице совместимости; примеры задач — в сценариях.