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 и без скрапинга каталогов. Проверяйте лицензии каждого нового источника.

Related MCP server: nl-file-search

Установка (Windows 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.

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

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 после запуска.

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

В GitHub запуск: Collect reviewed 3MF pilot, артефакт 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.

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

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

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

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

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

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

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

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

{
  "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; сторонние модели этой лицензией не покрываются.

Тесты

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, сравнение времени и расхода пластика.