# BlenderMCP Architecture Documentation
## Обзор
BlenderMCP следует модульной архитектуре с чёткой separation of concerns. Все инструменты и промпты организованы в отдельные модули по функциональности.
## Принципы организации кода
### 🚫 НЕ ОПРЕДЕЛЯЙТЕ инструменты напрямую в server.py!
**Правило:** `server.py` содержит только:
- Инфраструктурный код (подключение, MCP сервер)
- Импорты инструментов
- Тонкие обёртки с декораторами `@mcp.tool()` и `@mcp.prompt()`
**Вся логика инструментов** должна быть в соответствующих модулях.
## Структура проекта
```
D:\repos\blender-mcp/
├── addon.py # Blender addon (socket server)
├── src/
│ ├── server.py # MCP server (только обёртки!)
│ ├── tools/ # 🔧 Core MCP tools
│ │ ├── __init__.py # Экспорт всех инструментов
│ │ ├── mesh_analysis.py # Анализ топологии
│ │ ├── remeshing.py # Decimation & shrinkwrap operations
│ │ ├── viewport.py # Управление viewport
│ │ ├── shading.py # Seams и sharp edges
│ │ ├── scene.py # Информация о сцене
│ │ ├── modifiers.py # Basic modifiers (legacy)
│ │ └── integrations/ # Внешние интеграции
│ │ ├── __init__.py
│ │ ├── polyhaven.py # PolyHaven asset library
│ │ ├── sketchfab.py # Sketchfab models
│ │ └── hyper3d.py # Hyper3D Rodin AI
│ ├── retopo_tools/ # 🎯 Advanced retopology workflows
│ │ ├── modifiers.py # Enhanced modifier tools
│ │ ├── mesh_ops.py # Mesh operations (symmetrize, smooth, etc.)
│ │ ├── mesh_analysis.py # Tool schemas (not implementations)
│ │ ├── selection.py # Selection tools
│ │ ├── snapping.py # Snapping configuration
│ │ ├── remesh.py # Voxel & QuadriFlow remeshing
│ │ ├── camera.py # Camera controls
│ │ ├── baking.py # Texture baking
│ │ └── io.py # Import/Export
│ └── prompts/ # 💬 MCP промпты
│ ├── __init__.py
│ ├── retopo.py # Retopology pipeline
│ └── asset_creation.py # Asset creation strategy
├── features/ # 📝 BDD спецификации (Gherkin)
└── docs/
```
## tools/ vs retopo_tools/ - Когда что использовать?
### tools/ - Core Operations (Базовые операции)
**Назначение:** Фундаментальные операции Blender, применимые к широкому спектру задач
**Включает:**
- **mesh_analysis.py** - Получение статистики и обнаружение проблем топологии
- **remeshing.py** - Децимация (decimate) и проекция (shrinkwrap_reproject)
- **viewport.py** - Управление видом и камерой viewport
- **shading.py** - Маркировка UV швов и острых рёбер
- **scene.py** - Информация о сцене и выполнение Python кода
- **modifiers.py** - Базовые модификаторы (устаревшие, сохранены для совместимости)
- **integrations/** - Внешние библиотеки ассетов (PolyHaven, Sketchfab, Hyper3D)
**Когда добавлять инструмент в tools/:**
- Инструмент решает общую задачу (не специфичную для ретопологии)
- Инструмент используется в разных workflow (текстурирование, моделирование, рендеринг)
- Инструмент предоставляет базовую функциональность Blender
### retopo_tools/ - Retopology Workflows (Специализированные операции)
**Назначение:** Продвинутые инструменты, оптимизированные специально для ретопологии
**Включает:**
- **remesh.py** - Voxel и QuadriFlow ремешинг (улучшенные реализации с валидацией)
- **modifiers.py** - Модификаторы для ретопологии (Mirror, Shrinkwrap, DataTransfer и др.)
- **mesh_ops.py** - Операции с mesh (симметрия, сглаживание, слияние, очистка)
- **mesh_analysis.py** - JSON схемы для MCP регистрации (не реализации)
- **selection.py** - Инструменты выделения (non-manifold selection)
- **snapping.py** - Конфигурация привязки для ретопологии
- **camera.py** - Управление камерами для референсов
- **baking.py** - Запекание Normal/AO/Curvature карт
- **io.py** - Импорт/экспорт ретопологизированных mesh
**Когда добавлять инструмент в retopo_tools/:**
- Инструмент специфичен для ретопологии
- Инструмент требует расширенной валидации входных данных
- Инструмент part of a retopo pipeline (зависит от других retopo инструментов)
- Инструмент оптимизирован для создания low-poly из high-poly
### Migrация и консолидация
**История:**
- Изначально все инструменты были в `tools/`
- Ретопология-специфичные инструменты были выделены в `retopo_tools/` для лучшей организации
- Некоторые инструменты были улучшены при переносе (например, `remesh_voxel` имеет больше параметров и валидации чем старый `voxel_remesh`)
**Текущее состояние дубликатов:**
- ✅ **remeshing** - Voxel/QuadriFlow ПЕРЕНЕСЕНЫ в `retopo_tools/remesh.py`, decimate/shrinkwrap остались в `tools/remeshing.py`
- ✅ **modifiers** - НЕ дубликаты: `tools/modifiers.py` содержит legacy функции, `retopo_tools/modifiers.py` содержит улучшенные версии
- ✅ **mesh_analysis** - НЕ дубликаты: `tools/mesh_analysis.py` содержит реализации, `retopo_tools/mesh_analysis.py` содержит только схемы
## Модули инструментов
### 1. tools/mesh_analysis.py
**Назначение:** Анализ топологии mesh объектов
**Инструменты:**
- `mesh_stats(ctx, blender_connection, active_only)` - Статистика топологии
- `detect_topology_issues(ctx, blender_connection, angle_sharp, distance_doubles)` - Обнаружение проблем
**Когда использовать:** Для диагностики mesh перед/после ремеша
### 2. tools/remeshing.py
**Назначение:** Операции децимации и проекции mesh
**Инструменты:**
- `decimate(...)` - Редукция полигонов
- `shrinkwrap_reproject(...)` - Проекция на surface
**Когда использовать:** Для редукции полигонов или проекции low-poly на high-poly
**ПРИМЕЧАНИЕ:** Voxel и QuadriFlow remeshing перенесены в `retopo_tools/remesh.py`
### 3. tools/viewport.py
**Назначение:** Управление viewport (проекция, выравнивание)
**Инструменты:**
- `set_view_projection(...)` - ORTHO/PERSP переключение
- `align_view_to_axis(...)` - Выравнивание по осям
- `frame_selected(...)` - Фреймирование объектов
**Когда использовать:** Для настройки view перед скриншотами, inspection
### 4. tools/shading.py
**Назначение:** Подготовка UV и shading
**Инструменты:**
- `mark_seams_by_angle(...)` - Автоматическая маркировка UV seams
- `mark_sharp_by_angle(...)` - Маркировка sharp edges
**Когда использовать:** После ремеша, перед UV unwrap
### 5. tools/scene.py
**Назначение:** Базовая работа со сценой
**Инструменты:**
- `get_scene_info(...)` - Информация о сцене
- `get_object_info(...)` - Информация об объекте
- `get_viewport_screenshot(...)` - Захват viewport
- `execute_blender_code(...)` - Выполнение Python кода
**Когда использовать:** Для inspection, debugging, fallback к scripting
### 6. tools/integrations/polyhaven.py
**Назначение:** Интеграция с PolyHaven asset library
**Инструменты:**
- `get_polyhaven_status(...)` - Проверка доступности
- `get_polyhaven_categories(...)` - Категории assets
- `search_polyhaven_assets(...)` - Поиск assets
- `download_polyhaven_asset(...)` - Загрузка assets
- `set_texture(...)` - Применение текстур
**Когда использовать:** Для HDRIs, текстур, готовых моделей
### 7. tools/integrations/sketchfab.py
**Назначение:** Интеграция со Sketchfab marketplace
**Инструменты:**
- `get_sketchfab_status(...)`
- `search_sketchfab_models(...)`
- `download_sketchfab_model(...)`
**Когда использовать:** Для реалистичных моделей, широкий выбор
### 8. tools/integrations/hyper3d.py
**Назначение:** AI-генерация моделей через Hyper3D Rodin
**Инструменты:**
- `get_hyper3d_status(...)`
- `generate_hyper3d_model_via_text(...)`
- `generate_hyper3d_model_via_images(...)`
- `poll_rodin_job_status(...)`
- `import_generated_asset(...)`
**Когда использовать:** Для уникальных моделей, которых нет в библиотеках
## Модули промптов
### 1. prompts/retopo.py
**Назначение:** Пошаговое руководство по retopology pipeline
**Промпт:** `retopo_pipeline()`
**Содержит:**
- Phase 1: Analysis & Preparation
- Phase 2: Remeshing Strategy (3 варианта)
- Phase 3: Refinement
- Phase 4: Visual Inspection
- Common Workflows
### 2. prompts/asset_creation.py
**Назначение:** Стратегия создания assets с приоритизацией интеграций
**Промпт:** `asset_creation_strategy()`
**Содержит:**
- Проверка доступных интеграций
- Приоритеты источников (PolyHaven/Sketchfab/Hyper3D)
- Fallback к scripting
## Паттерн добавления нового инструмента
### Шаг 1: Создайте функцию в соответствующем модуле
```python
# src/tools/your_module.py
from mcp.server.fastmcp import Context
import logging
logger = logging.getLogger("BlenderMCPServer")
def your_tool_name(
ctx: Context,
blender_connection,
param1: str,
param2: int = 42
) -> str:
"""
Описание инструмента.
Parameters:
- param1: Описание параметра 1
- param2: Описание параметра 2 (default: 42)
Returns описание результата.
"""
try:
result = blender_connection.send_command("command_name", {
"param1": param1,
"param2": param2
})
if "error" in result:
return f"Error: {result['error']}"
# Форматирование результата
output = "Success!\n\n"
output += f"Result: {result.get('value')}\n"
return output
except Exception as e:
logger.error(f"Error in your_tool: {str(e)}")
return f"Error in your_tool: {str(e)}"
```
### Шаг 2: Экспортируйте из __init__.py
```python
# src/tools/__init__.py
from .your_module import your_tool_name
__all__ = [
# ... existing tools
'your_tool_name',
]
```
### Шаг 3: Импортируйте в server.py
```python
# В секции TOOL AND PROMPT IMPORTS в server.py
from .tools.your_module import your_tool_name as your_tool_name_impl
```
### Шаг 4: Создайте обёртку с декоратором
```python
# В секции TOOL WRAPPERS в server.py
@mcp.tool()
def your_tool_name(ctx: Context, param1: str, param2: int = 42) -> str:
"""
<СКОПИРУЙТЕ DOCSTRING ИЗ РЕАЛИЗАЦИИ - ВАЖНО ДЛЯ MCP DISCOVERY!>
"""
return your_tool_name_impl(ctx, get_blender_connection(), param1, param2)
```
### Шаг 5: Добавьте handler в addon.py
```python
# В BlenderMCPServer._execute_command_internal() в addon.py
handlers = {
# ... existing handlers
"command_name": self.your_method,
}
```
## Сигнатуры функций
### Инструменты (tools)
```python
def tool_name(
ctx: Context, # MCP context (всегда первый параметр)
blender_connection, # Blender connection object
param1: type, # Параметры инструмента
param2: type = default
) -> str: # Или Image для скриншотов
```
### Промпты (prompts)
```python
def prompt_name() -> str: # Промпты не принимают параметры
"""Docstring"""
return """Длинный текст промпта..."""
```
## Соглашения по коду
### Naming Conventions
- **Модули:** `snake_case.py`
- **Функции:** `snake_case_verb_noun()`
- **Приватные функции:** `_private_helper()`
- **Константы:** `UPPER_CASE`
### Docstrings
Обязательны для всех public функций. Формат:
```python
"""
Краткое описание в одну строку.
Опциональное расширенное описание.
Parameters:
- param1: Описание (type, default if applicable)
- param2: Описание
Returns описание результата.
"""
```
### Error Handling
Все инструменты должны:
1. Использовать try/except блоки
2. Логировать ошибки через logger
3. Возвращать понятные сообщения пользователю
4. Проверять preconditions перед операциями
```python
try:
# Precondition check
if not valid:
return "Error: Precondition not met. Suggestion: ..."
# Main logic
result = blender_connection.send_command(...)
if "error" in result:
return f"Error: {result['error']}"
# Format output
return formatted_output
except Exception as e:
logger.error(f"Error in tool: {str(e)}")
return f"Error in tool: {str(e)}"
```
## Testing
### BDD спецификации
Все features документированы в Gherkin:
- `features/*.feature` - Given/When/Then сценарии
- Используются как спецификация И документация
### Ручное тестирование
1. Запустите Blender addon
2. Запустите MCP server: `uvx blender-mcp`
3. Подключитесь через Claude Desktop
4. Проверьте tool discovery: "List available tools"
5. Тестируйте каждый инструмент
## Метрики качества
### До рефакторинга
- `server.py`: **1514 строк** (монолит)
- Все инструменты в одном файле
- Сложно навигировать
- Сложно добавлять новые features
### После рефакторинга
- `server.py`: **763 строки** (только обёртки)
- **9 отдельных модулей** с чёткими зонами ответственности
- Легко найти нужный код
- Простое добавление новых инструментов
## Зависимости между модулями
```
server.py
├── tools/
│ ├── mesh_analysis.py
│ ├── remeshing.py
│ ├── viewport.py
│ ├── shading.py
│ ├── scene.py
│ └── integrations/
│ ├── polyhaven.py
│ ├── sketchfab.py
│ └── hyper3d.py
└── prompts/
├── retopo.py
└── asset_creation.py
addon.py (независимо)
```
**Правило:** Модули tools/ и prompts/ НЕ импортируют друг друга. Они независимы и импортируются только в server.py.
## Performance Considerations
- **Lazy loading:** Модули импортируются только при старте server.py
- **Connection pooling:** `get_blender_connection()` переиспользует соединение
- **Minimal overhead:** Обёртки в server.py тонкие (одна строка)
## Безопасность
- `execute_blender_code` потенциально опасен - требует осторожности
- Все остальные инструменты безопасны (параметризованы)
- Нет arbitrary code execution в retopo workflow
## Roadmap
### Планируемые модули (см. BDD specs):
- `tools/baking.py` - Normal map baking
- `tools/io.py` - Import/Export (GLTF, FBX, OBJ)
- `tools/camera.py` - Camera controls
- `tools/render.py` - Batch rendering
## Заключение
Эта архитектура обеспечивает:
- ✅ **Модульность** - каждый модуль решает одну задачу
- ✅ **Maintainability** - легко найти и исправить код
- ✅ **Extensibility** - простое добавление новых features
- ✅ **Clarity** - понятная структура для новых разработчиков
- ✅ **Testability** - модули можно тестировать изолированно
**Помните:** server.py - это только точка входа. Вся логика - в модулях!
