# MCP-3d-printer

Исследовательский Python-проект для подготовки датасета FDM 3D-печати и первых рекомендаций по настройкам: **STL, 3MF, CLI, MCP для Cursor**.

**Статус: MVP 0.1, нейросеть пока не обучена.** Рекомендации основаны на простых правилах, а не на проверенном качестве печати. Прямого управления принтером, отправки G-code или запуска нагрева нет.

## Что работает

- Анализ локальных STL и 3MF: габариты, число треугольников, приблизительная доля поверхностей, направленных вниз;
- Чтение части настроек Bambu Studio / OrcaSlicer из `Metadata/project_settings.config`, если файл проекта их содержит;
- Базовые рекомендации по PLA, PETG, ABS и TPU, кандидатам ориентации и поддержкам (эвристика, требует проверки);
- Индексация **разрешённых локальных моделей**, указанных в манифесте с `license`, SHA-256, `records.jsonl` и `training.csv`;
- MCP tools `inspect_3d_file`, `recommend_3d_print`, `index_licensed_3d_dataset` для Cursor.

Инспектор, индексатор и MCP не обращаются к сети. Отдельный демонстрационный сборщик загружает только заранее перечисленные CC0-модели с GitHub, без доступа к MakerWorld/Printables и без скрапинга каталогов. Проверяйте лицензии каждого нового источника.

## Установка (Windows PowerShell)

```powershell
git clone https://github.com/amba-pro/MCP-3d-printer.git
cd MCP-3d-printer
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -e .
```

В Linux: `source .venv/bin/activate` вместо `Activate.ps1`.

## Проверить локальную модель

```powershell
mcp3dp inspect "C:/models/test.3mf"
mcp3dp recommend "C:/models/test.stl" --material PLA --nozzle 0.4
```

`inspect` возвращает геометрию, встроенные настройки (если имеются), предупреждения. `recommend` возвращает параметры-отправные точки и ограничения. STL не хранит настройки слайсера.

## Проверенный сбор открытого датасета

21 октября 2026 тест на реальных файлах: 35/35 скачано, 35/35 проиндексировано, 0 ошибок. В 31 файле есть только геометрия, в 4 проектах Cura найдены явные переопределения некоторых настроек. Подтверждённых результатов физической печати — 0; модель оптимальных настроек на этом наборе пока обучать нельзя.

Источник: https://github.com/Ghostkeeper/SlicerTestModels (CC0-1.0); фиксированная версия e1bbc8eec047c2fb604b71f7e4793c3e0189fd6d. Полный перечень: sources/demo_cc0.json.

После установки проекта выполните из корня: python scripts/collect_demo_dataset.py --output .dataset/demo

В .dataset/demo появятся raw/ с исходными файлами, downloaded_manifest.json со ссылками и лицензиями, processed/training.csv, processed/records.jsonl, processed/skipped.json, download_failures.json и summary.json. Название training.csv не означает, что таблица уже имеет правильные ML-метки.

Сбор также проверяется GitHub Actions: https://github.com/amba-pro/MCP-3d-printer/actions/runs/39614717924 . Скачиваемый ZIP находится в разделе Artifacts.

Важная особенность Cura: данные читаются из отдельных слоёв Cura/*.cfg. Парсер берёт только явно заданные значения и оставляет формулы текстом; полный профиль с наследованием пресетов он не восстанавливает. Столбцы settings_source, settings_scope и settings_field_count позволяют отделить частичные настройки от полных профилей.

## Расширенный пилот Bambu/Orca 3MF (v0.3)

В дополнение к CC0-геометрии подготовлен **зафиксированный список 45 файлов-кандидатов**: 35 файлов Ghostkeeper/SlicerTestModels, 6 self-authored MIT-файлов SamiSalah221/3mf-to-glb, 4 проекта albanpetit/3d-printed-projects. У albanpetit README заявляет MIT, но ссылка на файл LICENSE в той ревизии отсутствует — этим записям назначается rights_reviewed=false до ручной проверки.

**Важно:** 45 — размер запланированного источникового набора, а не число полученных полноценных профилей! Фактическое количество скачанных, распарсенных и пригодных профилей отражается в summary.json после запуска.

```bash
python -m pip install -e .
python scripts/collect_pilot_dataset.py --output .dataset/pilot
```

В GitHub запуск: [Collect reviewed 3MF pilot](https://github.com/amba-pro/MCP-3d-printer/actions/workflows/collect-pilot-dataset.yml), артефакт `reviewed-3mf-pilot-dataset`.

Получите raw/ со скачанными исходными файлами, downloaded_manifest.json с лицензиями/коммитами, license_documents/ (лицензионные документы источников), processed/training.csv и отдельные файлы по категориям:

- `processed/geometry_only.csv` — 3D-геометрия без доступных настроек;
- `processed/settings_partial.csv` — частичные настройки / Cura overrides;
- `processed/profiles_candidates.csv` — Bambu/Orca проекты с ключевыми полями принтера/материала/слоя/заполнения;
- `processed/labeled_candidates.csv` — при наличии права использования и документированной *реальной физической печати*; при отсутствии доказательств файл будет пустой;
- `processed/quality_report.json` — количественная оценка всех категорий.

Запись профиля не доказывает оптимальность настроек. В пилоте исходные файлы не имеют подтверждённых меток качества реальной печати: ни один из этих файлов **не считается обучающим эталоном**. Ошибки обработки и причины неполноты сохраняются отдельно. Наполнение 100–300 реальных разрешённых проектов с profile coverage и ground truth отслеживается в [issue #1](https://github.com/amba-pro/MCP-3d-printer/issues/1).

## Датасет из файлов с известными правами

Скачайте вручную файлы, которые можно использовать для вашего исследования, или возьмите собственные проекты. Положите их в `C:/models`. Создайте `C:/manifest.json` по примеру [manifest.example.json](examples/manifest.example.json). Укажите относительный `path`, обязательную `license`, автора и происхождение. Добавляйте `quality_score_0_5` и `print_outcome` **только после проверки физической печати**.

```powershell
mcp3dp index --folder "C:/models" --manifest "C:/manifest.json" --out "C:/printer-dataset"
```

Получите `records.jsonl`, `training.csv`, `skipped.json`. Файлы моделей остаются на месте и в репозиторий не загружаются.

**Для обучения:** красивые профили из интернета — не подтверждение оптимальности. Нужны связки «геометрия + параметры + принтер + пластик + реально измеренное качество/время/дефекты». Делайте разделение train/test по семействам моделей, чтобы исключить утечку через дубликаты.

## Подключить MCP к Cursor

```powershell
python -m pip install -e '.[mcp]'
```

Пример настроек Cursor (заменить абсолютный путь к Python):

```json
{
  "mcpServers": {
    "mcp-3d-printer": {
      "command": "C:/path/to/MCP-3d-printer/.venv/Scripts/python.exe",
      "args": ["-m", "mcp_3d_printer.mcp_server"]
    }
  }
}
```

На Linux используйте `<project>/.venv/bin/python`. Подключать MCP стоит только доверенным агентам: инструменты читают заданные локальные пути.

## Границы первой версии

- STL предполагается в **миллиметрах**: формат не содержит единиц.
- 3MF читает только первый `3D/*.model` и не применяет сложные трансформации сборки; в многокомпонентных проектах габариты неточны.
- Профили 3MF могут отсутствовать, часть настроек и проприетарных расширений не поддерживается.
- Нависания зависят от ориентации граней и не учитывают bridges; предлагаемые оси используют bounding box, а не геометрию контакта.
- Файлы ограничены 100 MiB, ZIP-элемент — 20 MiB; крупные проекты могут быть отклонены.
- Температуры, скорость, заполнение и поддержки примерные. Сверяйте с инструкциями производителя пластика и ограничениями принтера.
- Без размеченных результатов реальной печати учить модель «правильной печати» преждевременно.
- Код — MIT; сторонние модели этой лицензией **не покрываются**.

## Тесты

```powershell
python -m unittest discover -s tests -v
```

## Roadmap

1. **0.1 (готово):** STL/3MF, сбор легального датасета, первые правила, MCP.
2. **0.2:** корректная ориентация/поддержки и совместимость профилей, тесты на реальных проектах.
3. **0.3:** ML на размеченных успехах и дефектах, оценка на отложенных деталях.
4. **0.4:** dry-run интеграция с OrcaSlicer CLI, сравнение времени и расхода пластика.