# 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 ([получить здесь](https://developer.hyper3d.ai/))
- `uv` (рекомендуется) или `pip`

## Установка

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

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

```bash
# 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 протокол:

```json
{
  "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: убедитесь, что пути к изображениям корректны

## Разработка

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

```bash
pip install -e ".[dev]"
```

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

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

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

```bash
pytest
```

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

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

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

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

```bash
# Базовый запуск
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](tests/README.md)

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

```bash
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](.github/workflows/tests.yml)

## Ссылки

- [Rodin Gen-2 API Documentation](https://developer.hyper3d.ai/)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)

## Лицензия

MIT