Blender-Mind-MCP (Продакшн AI 3D-моделинг и мост Blender)

Продакшн-уровневый сервер Model Context Protocol (MCP) и экосистема аддонов Blender для автоматизированного 3D-моделинга, процедурной генерации ассетов, создания шейдеров и мультимодальной инспекции вьюпорта.

🏗️ Предшествующие работы и архитектурное вдохновение

Этот проект включает архитектурные уроки и эталоны ведущих GitHub-проектов Blender AI (таких как ahujasid/blender-mcp и djeada/blender-mcp-server):

1. Потокобезопасная диспетчеризация в главном потоке: Python C-API (bpy) в Blender не является потокобезопасным. Как показал анализ проблем сообщества, выполнение вызовов bpy в потоках прослушивания сырых сокетов вызывает повреждение памяти и ошибки сегментации. Наш аддон Blender использует потокобезопасный queue.Queue в связке с bpy.app.timers, чтобы гарантировать, что все изменения сцены выполняются строго в главном цикле рендеринга/GUI Blender.

2. Изоляция шагов отмены: Каждое выполнение AI-кода обрамляется вызовом bpy.ops.ed.undo_push(), что обеспечивает бесшовный откат через Ctrl+Z в Blender.

3. Мультимодальный захват вьюпорта: Использует внеэкранный рендеринг OpenGL (bpy.ops.render.opengl) для возврата PNG-скриншотов 3D-вьюпорта в кодировке Base64 напрямую мультимодальным моделям зрения.

4. Гексагональная архитектура (порты и адаптеры): Отделяет чистую генерацию 3D-геометрии от физических драйверов, поддерживая как живые Socket-соединения (127.0.0.1:9876), так и пакетную обработку через headless CLI (blender -b), а также офлайн-симуляцию процедурных бинарных glTF.

Related MCP server: Blender MCP Server

📦 Структура проекта

blender-mind-mcp/
├── addon/
│   └── blender_mcp_addon.py       # Full Blender 3.x/4.x Addon (UI Sidebar Panel, Socket Server, Viewport Capture)
├── src/
│   ├── index.ts                   # stdio JSON-RPC MCP Server entry point
│   ├── bridge/
│   │   └── socket_client.ts       # Robust TCP Socket Client with reconnect & timeout handling
│   ├── core/
│   │   └── domain/
│   │       ├── types.ts           # 3D Domain Types (Scene, Mesh, Material, Modifier, Transform)
│   │       ├── scene.ts           # Pure in-memory 3D scene graph & polygon math
│   │       └── bpy_generator.ts   # Modern Blender 4.x/3.x Python code synthesizer
│   ├── ports/
│   │   └── driver.port.ts         # BlenderDriverPort interface specification
│   ├── adapters/
│   │   ├── live_socket.adapter.ts # Live Socket Adapter (talks to active Blender GUI)
│   │   ├── blender_cli.adapter.ts # Headless CLI Adapter (talks to blender.exe)
│   │   └── mock_geometry.adapter.ts # Offline Simulation Adapter (glTF & OBJ binary synthesis)
│   └── tools/
│       └── index.ts               # 10 MCP Tools registry & dispatcher
├── tests/
│   ├── unit/                      # L1: Domain math & Python code generation
│   ├── contract/                  # L2: MCP tool schemas & argument contracts
│   ├── integration/               # L3: Binary glTF headers & TCP Socket Bridge
│   └── run_tests.ts               # Complete Truth Ladder test runner
├── package.json
└── tsconfig.json

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

1. Установка аддона в Blender

1. Откройте Blender (3.6+ или 4.x).

2. Перейдите в Edit > Preferences > Add-ons > Install... (или стрелку Install from Disk в 4.2+).

3. Выберите addon/blender_mcp_addon.py.

4. Включите Development: Blender MCP Bridge.

5. В 3D Viewport нажмите N, чтобы открыть боковую панель, нажмите на вкладку Blender MCP и нажмите Start MCP Server.

2. Настройка MCP-клиента (Antigravity / Claude / Codex)

Добавьте в конфигурацию MCP вашего проекта или в глобальную конфигурацию (.mcp.json):

{
  "mcpServers": {
    "blender": {
      "command": "node",
      "args": [
        "--disable-warning=ExperimentalWarning",
        "--experimental-strip-types",
        "C:/Users/a1691/Documents/antigravity/noble-hypatia/src/index.ts"
      ]
    }
  }
}

🛠️ 10 основных MCP-инструментов

🧪 Верификация по лестнице истинности

npm test

Выполняет все 6 тестовых наборов по 4-уровневой лестнице истинности:

• L1 Unit: 100% чистое доменное моделирование и AST-проверки синтезатора Python-кода.

• L2 Contract: Определения схем и проверка диспетчеризации для всех 10 инструментов.

• L3 Integration: Проверка бинарного заголовка glTF v2 (0x46546C67) и структуры OBJ.

• L3 Integration: Живой loopback-тест TCP Socket «клиент-сервер» на 127.0.0.1:9899.

• L4 E2E: Живой сквозной обмен stdio JSON-RPC через pipe.