rodin-gen2-mcp 0.3.4

MCP Server for Rodin Gen-2 3D Generation API

Rodin Gen-2 MCP Server

MCP (Model Context Protocol) сервер для интеграции с Rodin Gen-2 API - мощным сервисом генерации 3D моделей.

Возможности

• 🎨 Text-to-3D: Генерация 3D моделей из текстовых описаний
• 🖼️ Image-to-3D: Создание 3D моделей из изображений (до 5 изображений)
• 📊 Проверка статуса: Отслеживание прогресса генерации
• 💾 Загрузка результатов: Автоматическое скачивание готовых 3D моделей
• 🔧 Гибкая настройка: Поддержка различных форматов, материалов и параметров качества
• 🚀 MCP протокол: Интеграция с любыми MCP-совместимыми клиентами (Claude Desktop, и др.)

Требования

• Python 3.10 или выше
• API ключ Rodin Gen-2 (получить здесь)
• uv (рекомендуется) или pip

Установка

Вариант 1: Использование uv (рекомендуется)

1. Установите uv:

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

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

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

Добавьте в конфигурацию любого IDE, поддерживающего MCP протокол:

{
  "mcpServers": {
    "rodin-gen2-mcp": {
      "command": "uvx",
      "args": ["rodin-gen2-mcp"],
      "env": {
        "RODIN_API_KEY": "your_api_key_here"
      }
    }
  }
}

Доступные инструменты

1. generate_3d_text_to_3d

Генерирует 3D модель из текстового описания.

Параметры:

• prompt (обязательно): Текстовое описание модели
• seed: Seed для воспроизводимости (0-65535)
• geometry_file_format: Формат файла (glb, usdz, fbx, obj, stl)
• material: Тип материала (PBR, Shaded, All)
• mesh_simplify: Упростить меш (true/false)
• quality_override: Количество полигонов
• bbox_condition: Размеры bounding box [width, height, length]

Пример в Claude:

Создай 3D модель футуристического робота

2. generate_3d_image_to_3d

Генерирует 3D модель из изображения(й).

Параметры:

• image_paths (обязательно): Список путей к изображениям (до 5)
• prompt: Дополнительное текстовое описание
• use_original_alpha: Использовать альфа-канал
• seed: Seed для воспроизводимости (0-65535)
• geometry_file_format: Формат файла (glb, usdz, fbx, obj, stl)
• material: Тип материала (PBR, Shaded, All)
• mesh_simplify: Упростить меш (true/false)
• quality_override: Количество полигонов
• condition_mode: Режим для множественных изображений
• bbox_condition: Размеры bounding box [width, height, length]

Пример в Claude:

Создай 3D модель из изображения C:\Users\user\image.jpg

3. check_task_status

Проверяет статус задачи генерации.

Параметры:

• task_uuid (обязательно): UUID задачи

Пример в Claude:

Проверь статус задачи 123e4567-e89b-12d3-a456-426614174000

4. download_result

Загружает готовую 3D модель.

Параметры:

• task_uuid (обязательно): UUID завершенной задачи
• output_path: Путь для сохранения (опционально)

Пример в Claude:

Загрузи результат задачи 123e4567-e89b-12d3-a456-426614174000

Примеры использования

Полный рабочий процесс

1. Генерация из текста:

Создай 3D модель красного спортивного автомобиля в формате fbx

2. Проверка статуса:

Проверь статус задачи <UUID из предыдущего ответа>

3. Загрузка результата:

Загрузи результат задачи <UUID>

Генерация из изображения

Создай 3D модель из этих изображений:
- C:\Users\user\front.jpg
- C:\Users\user\side.jpg
с материалом PBR и упрощением меша

Поддерживаемые форматы

Форматы файлов

• GLB (по умолчанию) - GL Transmission Format Binary
• USDZ - Universal Scene Description
• FBX - Filmbox
• OBJ - Wavefront Object
• STL - Stereolithography

Типы материалов

• PBR (по умолчанию) - Physically Based Rendering
• Shaded - Затененный материал
• All - Все типы материалов

Цены

• Базовая стоимость: 0.5 кредита за генерацию
• HighPack addon: +1 кредит за генерацию

Дополнительные параметры бесплатны.

Устранение неполадок

Сервер не отображается в Claude Desktop

1. Проверьте правильность путей в claude_desktop_config.json
2. Убедитесь, что используете абсолютные пути
3. Перезапустите Claude Desktop полностью (Quit, не просто закрытие окна)
4. Проверьте логи: ~/Library/Logs/Claude/mcp*.log (macOS) или %APPDATA%\Claude\logs\ (Windows)

Ошибка "RODIN_API_KEY не установлен"

1. Убедитесь, что файл .env существует в корне проекта
2. Проверьте, что в .env правильно указан ключ: RODIN_API_KEY=your_key
3. Перезапустите сервер

Ошибки при генерации

• Проверьте интернет-соединение
• Убедитесь, что API ключ действителен
• Проверьте баланс кредитов в вашем аккаунте Rodin
• Для Image-to-3D: убедитесь, что пути к изображениям корректны

Зависание команд

Если команды зависают, используйте детальное логирование для диагностики:

python rodin_gen2_server.py --log-file rodin_debug.log

Логи будут записываться в указанный файл с подробной информацией о:

• HTTP запросах и времени их выполнения
• Параметрах генерации
• Прогрессе загрузки файлов
• Статусе задач

Подробнее см. LOGGING.md

Разработка

Установка зависимостей для разработки

pip install -e ".[dev]"

Запуск тестов

Проект покрыт комплексным набором unit и integration тестов.

Запуск всех тестов

pytest

Запуск с покрытием кода

pytest --cov=. --cov-report=html --cov-report=term

HTML отчет будет доступен в htmlcov/index.html

Использование скрипта запуска

# Базовый запуск
python run_tests.py

# С покрытием кода
python run_tests.py --coverage

# С HTML отчетом
python run_tests.py --coverage --html

# Подробный вывод
python run_tests.py -v

# Конкретный тест
python run_tests.py -t tests/test_main.py

Покрытие кода

Тесты покрывают:

• ✅ FastAPI сервер (main.py)

  • Все эндпоинты
  • RodinClient класс
  • Обработка ошибок

• ✅ MCP сервер (rodin_gen2_server.py)

  • Все MCP инструменты
  • HTTP запросы к API
  • Валидация параметров
  • Фоновая загрузка файлов
  • Обработка ошибок и edge cases

Подробная документация: tests/README.md

Форматирование кода

black rodin_gen2_server.py main.py
ruff check rodin_gen2_server.py main.py

CI/CD

Проект включает GitHub Actions workflow для автоматического запуска тестов на:

• Ubuntu, Windows, macOS
• Python 3.10, 3.11, 3.12

См. .github/workflows/tests.yml

Ссылки

• Rodin Gen-2 API Documentation
• Model Context Protocol Specification
• MCP Python SDK

Лицензия

MIT