Bonsai-mcp — интеграция протокола контекста модели для IFC через IfcOpenShell и Blender

Bonsai-mcp — это ответвление BlenderMCP , которое расширяет исходную функциональность за счет специальной поддержки моделей IFC (Industry Foundation Classes) через Bonsai (ранее называвшийся BlenderBIM). Эта интеграция представляет собой платформу, позволяющую LLM читать и изменять файлы IFC.

Функции

• Специфические функции IFC : запросы к моделям IFC, анализ пространственных структур и изучение элементов зданий.

• Включено одиннадцать инструментов IFC : проверка информации о проекте, составление списка объектов, проверка свойств, исследование пространственной структуры, анализ взаимосвязей и многое другое.

• Последовательное мышление : включает в себя инструмент последовательного мышления из modelcontextprotocol/servers для структурированного решения проблем.

• Инструмент «Выполнить код» из оригинальной реализации BlenderMCP : создание и изменение объектов, применение материалов и выполнение кода Python в Blender.

Related MCP server: BlenderMCP

Компоненты

Система состоит из двух основных компонентов:

1. Дополнение Blender ( addon.py ) : дополнение Blender, которое создает сокет-сервер в Blender для получения и выполнения команд, включая специфичные для IFC операции.

2. MCP-сервер ( tools.py ) : сервер Python, реализующий протокол контекста модели и подключающийся к дополнению Blender.

Установка — через настройки клиента MCP

Предпосылки

• Blender 4.0 или новее

• Python 3.12 или новее

• менеджер пакетов uv

• Дополнение Bonsai BIM для Blender (для функциональности IFC)

Установка УФ:

Мак:

brew  install  uv

Окна:

powershell  -c  "irm https://astral.sh/uv/install.ps1 | iex"

set  Path=C:\Users\[username]\.local\bin;%Path%

Для других платформ см. руководство по установке УФ-ламп .

Клонировать репозиторий

git  clone  https://github.com/JotaDeRodriguez/Bonsai_mcp

Клод для интеграции с рабочим столом

Отредактируйте файл claude_desktop_config.json (Claude > Настройки > Разработчик > Изменить конфигурацию), включив в него:

{
    "mcpServers": {
        "Bonsai-mcp": {
            "command": "uv",
            "args": [
              "--directory",
              "\\your\\path\\to\\Bonsai_mcp",
              "run",
              "tools.py"
          ]
        }
    }
}

Установка через Docker

Репозиторий поставляется с Dockerfile, который делает развертывание простым и единообразным в различных средах.

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

# Clone the repository
git clone https://github.com/JotaDeRodriguez/Bonsai_mcp
cd Bonsai_mcp

# Build the Docker image
docker build -t bonsai_mcp .

# Run the container
docker run -p 8000:8000 --name bonsai_mcp bonsai_mcp

После запуска контейнер предоставит инструменты MCP в виде API REST/OpenAPI по адресу http://localhost:8000 .

• Чтобы проверить установку, откройте браузер и перейдите по адресу

• http://localhost:8000/docs

• Вы увидите пользовательский интерфейс Swagger со всеми доступными конечными точками.

• Протестируйте конечную точку, щелкнув по ней, затем нажмите «Попробовать» и «Выполнить».

Подключение к Open WebUI или другим API-клиентам

Чтобы подключить этот API к Open WebUI:

1. В Open WebUI перейдите в Настройки > Управление серверами инструментов.

2. Добавьте новое соединение с помощью:

   • URL-адрес: http://localhost:8000

   • Путь к спецификации OpenAPI: /openapi.json

   • Аутентификация: Нет (если не настроено иное)

Переменные среды

Контейнер Docker принимает несколько переменных среды для настройки своего поведения:

# Example with custom settings
docker run -p 8000:8000 \
  -e BLENDER_HOST=host.docker.internal \
  -e BLENDER_PORT=9876 \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  --name bonsai_mcp bonsai_mcp

Установка дополнения Blender

1. Загрузите файл addon.py из этого репозитория

2. Открыть блендер

3. Перейдите в меню «Правка» > «Настройки» > «Дополнения».

4. Нажмите «Установить...» и выберите файл addon.py

5. Включите дополнение, установив флажок рядом с «Интерфейс: Blender MCP - IFC».

Использование

Начало соединения

1. В Blender перейдите на боковую панель 3D-вида (нажмите N, если она не видна)

2. Найдите вкладку «Blender MCP - IFC».

3. Нажмите «Подключиться к Клоду».

4. Убедитесь, что сервер MCP запущен.

Использование с Клодом

После подключения вы увидите значок молотка в интерфейсе Клода с инструментами для интеграции Blender MCP IFC.

Инструменты МФК

В этот репозиторий входят девять специализированных инструментов IFC, которые позволяют выполнять комплексные запросы и манипулировать моделями IFC:

get_ifc_project_info : Извлекает основную информацию о проекте IFC, включая имя, описание и количество различных типов сущностей. Пример: «Какова основная информация об этом проекте IFC?»

list_ifc_entities : Перечисляет сущности IFC определенного типа (стены, двери, пространства и т. д.) с возможностью ограничения результатов и фильтрации по выбору. Пример: «Перечислить все стены в этой модели IFC» или «Показать мне окна в этом здании»

get_ifc_properties : Извлекает все свойства определенной сущности IFC по ее GlobalId или из выбранных в данный момент объектов. Пример: «Каковы свойства этой стены с идентификатором 1Dvrgv7Tf5IfTEapMkwDQY?»

get_ifc_spatial_structure : Получает пространственную иерархию модели IFC (участок, здание, этажи, пространства). Пример: "Покажите мне пространственную структуру этого здания"

get_ifc_relationships : Извлекает все отношения для определенной сущности IFC. Пример: «Каковы отношения входной двери?»

get_selected_ifc_entities : Получает информацию о сущностях IFC, соответствующих объектам, выбранным в данный момент в пользовательском интерфейсе Blender. Пример: «Расскажите мне об элементах, которые я выбрал в Blender»

get_user_view : Захватывает текущее окно просмотра Blender как изображение, позволяя визуализировать модель с точки зрения пользователя. Пример: "Покажи мне, что пользователь в данный момент видит в Blender"

export_ifc_data : Экспортирует данные IFC в структурированный файл JSON или CSV с возможностью фильтрации по типу сущности или уровню здания. Пример: «Экспортировать все данные о стенах в файл CSV»

place_ifc_object : Создает и размещает элемент IFC в модели в указанных координатах с необязательным поворотом. Пример: "Поместить дверь в координатах X:10, Y:5, Z:0 с поворотом на 90 градусов"

Выполнить код Blender

Устаревшая функция из оригинальной реализации MCP. Позволяет Клоду выполнять произвольный код Python в Blender. Используйте с осторожностью.

Инструмент последовательного мышления

Эта интеграция включает инструмент последовательного мышления для структурированного решения проблем и анализа. Он облегчает пошаговый процесс мышления, который может разветвляться, пересматриваться и адаптироваться по мере углубления понимания — идеально подходит для сложного анализа модели IFC или задач планирования.

Пример: «Используйте последовательное мышление для анализа энергоэффективности этого здания на основе модели IFC»

Примеры команд

Вот несколько примеров того, что вы можете попросить Клода сделать с моделями IFC:

• «Проанализируйте эту модель IFC и скажите, сколько в ней стен, дверей и окон»

• «Покажите мне пространственную структуру этой модели здания»

• «Перечислить все пространства в этой модели IFC и их свойства»

• «Определите все структурные элементы в этом здании»

• «Каковы взаимоотношения между этой стеной и другими элементами?»

• «Используйте последовательное мышление, чтобы создать план обслуживания этого здания на основе модели IFC»

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

• Проблемы с подключением : убедитесь, что сервер дополнений Blender запущен, а сервер MCP настроен в Claude.

• Модель IFC не загружается : убедитесь, что у вас установлено дополнение Bonsai BIM и загружен файл IFC.

• Ошибки тайм-аута : попробуйте упростить запросы или разбить их на более мелкие этапы.

Докер:

• Ошибки «Подключение отклонено» : убедитесь, что Blender запущен, дополнение включено и сервер запущен.

• Проблемы CORS : API имеет CORS, включенный по умолчанию для всех источников. Если у вас возникли проблемы, проверьте настройки CORS вашего клиента

• Проблемы производительности : Для больших моделей IFC ответы API могут быть медленнее. Рассмотрите возможность настройки тайм-аутов в вашем клиенте

Технические подробности

Интеграция IFC использует модуль Bonsai BIM для доступа к функциональности ifcopenshell в Blender. Связь осуществляется по тому же протоколу на основе JSON через сокеты TCP, что и оригинальный BlenderMCP.

Ограничения и соображения безопасности

• Инструмент execute_blender_code из оригинального проекта все еще доступен, позволяя запускать произвольный код Python в Blender. Используйте с осторожностью и всегда сохраняйте свою работу.

• Сложные модели IFC могут потребовать разбиения операций на более мелкие этапы.

• Производительность запросов IFC зависит от размера и сложности модели.

• Инструмент Get User View возвращает изображение в кодировке base64. Убедитесь, что клиент его поддерживает.

Вклады

Этот лицензированный MIT репозиторий открыт для форка, модификации и использования любым способом. Я открыт для идей и сотрудничества, так что не стесняйтесь обращаться ко мне за взносами.

Кредиты

• Оригинальный BlenderMCP от Сиддхарта Ахуджи

• Инструмент последовательного мышления от modelcontextprotocol/servers

• Интеграция IFC, основанная на дополнении Bonsai BIM для Blender

ДЕЛАТЬ

Интеграция и тестирование с большим количеством клиентов MCP