# snapmaker-u1-mcp

MCP server for Snapmaker U1 headless slicing on Ubuntu using **Snapmaker Orca** only.

It provides safe, reproducible primitives for AI agents:

- discover U1 models and profiles
- resolve Snapmaker Orca profile inheritance
- slice STL/3MF to G-code
- analyze generated G-code
- apply controlled process overrides
- compare slice variants

No GUI automation, no printer control, no automatic print start, and no fallback to upstream OrcaSlicer.

## Acknowledgements

This project was planned in the context of `Diterex/orcaslicer-mcp` and keeps attribution to that project while implementing a smaller Snapmaker U1/Snapmaker Orca-only server.

## Status

Implemented through Phase 10:

- `u1_health`
- `u1_list_models`
- `u1_list_profiles`
- `u1_slice`
- `u1_analyze_gcode`
- `u1_compare_slices`
- `u1_inspect_model`
- `u1_compare_orientations`
- `u1_render_preview`
- `u1_inject_thumbnail`

## Setup

```bash
export SNAPMAKER_ORCA_BIN=/path/to/snapmaker-orca/internal/orca-slicer
# or
export SNAPMAKER_ORCA_APPIMAGE=/path/to/Snapmaker-Orca.AppImage

export SNAPMAKER_PROFILE_DIR=/path/to/Snapmaker/Orca/profiles  # optional if auto-discovered
export U1_MODEL_DIR=$HOME/3D_Printing/models
export U1_OUTPUT_DIR=$HOME/3D_Printing/output
```

## CLI examples

```bash
PYTHONPATH=src python3 -m snapmaker_u1_mcp.server health
PYTHONPATH=src python3 -m snapmaker_u1_mcp.server list-models
PYTHONPATH=src python3 -m snapmaker_u1_mcp.server list-profiles --nozzle 0.4 --material PLA
# add --details to include full profile metadata
PYTHONPATH=src python3 -m snapmaker_u1_mcp.server inspect-model hase.stl
PYTHONPATH=src python3 -m snapmaker_u1_mcp.server render-preview hase.stl --view summary
PYTHONPATH=src python3 -m snapmaker_u1_mcp.server inject-thumbnail RUN_ID/plate_1.gcode --model hase.stl
```

Slice:

```bash
PYTHONPATH=src python3 -m snapmaker_u1_mcp.server slice hase.stl \
  --process "0.20 Standard @Snapmaker U1 (0.4 nozzle)" \
  --filament "Snapmaker PLA Basic @U1"
```

Slice with controlled overrides:

```bash
PYTHONPATH=src python3 -m snapmaker_u1_mcp.server slice hase.stl \
  --process "0.20 Standard @Snapmaker U1 (0.4 nozzle)" \
  --filament "Snapmaker PLA Basic @U1" \
  --overrides '{"wall_loops":5,"sparse_infill_density":20}'
```

Compare variants:

```bash
PYTHONPATH=src python3 -m snapmaker_u1_mcp.server compare-slices hase.stl \
  --filament "Snapmaker PLA Basic @U1" \
  --variants '[{"name":"standard","process":"0.20 Standard @Snapmaker U1 (0.4 nozzle)","overrides":{}},{"name":"strong","process":"0.20 Standard @Snapmaker U1 (0.4 nozzle)","overrides":{"wall_loops":5,"sparse_infill_density":20}}]'
```

Compare orientations:

```bash
PYTHONPATH=src python3 -m snapmaker_u1_mcp.server compare-orientations hase.stl \
  --process "0.20 Standard @Snapmaker U1 (0.4 nozzle)" \
  --filament "Snapmaker PLA Basic @U1" \
  --orientations '[{"name":"flat"}]'
```

Note: Snapmaker Orca Linux CLI `01.10.01.50` has been observed to segfault on some non-zero CLI rotation transforms. Such failures are reported per variant and logs are preserved; no fallback slicer is used.

## MCP usage

### 1. Create a virtual environment

```bash
cd /home/USER/snapmaker-u1-mcp
python3 -m venv .venv
.venv/bin/pip install -e .
```

### 2. Put models in the allowed model directory

```bash
mkdir -p /home/USER/3D_Printing/models
cp bracket.stl /home/USER/3D_Printing/models/
mkdir -p /home/USER/3D_Printing/output
```

The MCP server only accepts model paths relative to `U1_MODEL_DIR`.

### 3. Add the MCP server to your client config

A template is included at `.pi/mcp.example.json`.

Example MCP config:

```json
{
  "mcpServers": {
    "snapmaker-u1": {
      "type": "stdio",
      "command": "/home/USER/snapmaker-u1-mcp/.venv/bin/python",
      "args": ["-m", "snapmaker_u1_mcp.server"],
      "env": {
        "SNAPMAKER_ORCA_APPIMAGE": "/home/USER/Applications/Snapmaker-Orca.AppImage",
        "U1_MODEL_DIR": "/home/USER/3D_Printing/models",
        "U1_OUTPUT_DIR": "/home/USER/3D_Printing/output"
      }
    }
  }
}
```

Use `SNAPMAKER_ORCA_BIN` instead of `SNAPMAKER_ORCA_APPIMAGE` if you have the internal Snapmaker Orca binary path.

### 4. Verify from your MCP client

Ask your MCP client/agent:

```text
Check my Snapmaker U1 slicer health.
```

Expected tool call:

```text
u1_health
```

Then ask:

```text
List my available PLA profiles for a 0.4 mm Snapmaker U1 nozzle.
```

Expected tool call:

```text
u1_list_profiles(nozzle=0.4, material="PLA")
```

### 5. Example MCP prompts

Slice a model:

```text
Slice hase.stl for my Snapmaker U1 with the 0.20 Standard 0.4 nozzle process and Snapmaker PLA Basic filament.
```

Compare stronger settings:

```text
Compare hase.stl baseline against 5 walls and 20% infill. Keep all generated G-code files.
```

Inspect and preview:

```text
Inspect hase.stl and render a summary preview.
```

Compare orientations:

```text
Compare flat, 90 degrees around X, and 90 degrees around Y for hase.stl.
```

### Available MCP tools

- `u1_health`
- `u1_list_models`
- `u1_list_profiles`
- `u1_slice`
- `u1_analyze_gcode`
- `u1_compare_slices`
- `u1_inspect_model`
- `u1_compare_orientations`
- `u1_render_preview`
- `u1_inject_thumbnail`
- `u1_smoke_slice` regression/helper

## MCP response size

MCP tools return compact responses by default to avoid filling the agent context with logs and profile metadata.

Use these only when needed:

- `u1_list_profiles(..., details=true)` for full profile metadata
- `u1_slice(..., verbose=true)` for command and log tails
- `u1_compare_slices(..., verbose=true)` for per-variant verbose slice data
- `u1_compare_orientations(..., verbose=true)` for per-orientation verbose slice data

Full reproducibility artifacts are always written to the run directory even when MCP responses are compact.

## Run artifacts

Each slice creates a unique run directory containing:

```text
request.json
command.json
profiles/machine.json
profiles/process.json
profiles/filament.json
stdout.log
stderr.log
analysis.json
plate_1.gcode
```

Original Snapmaker profiles are never modified.

## Tests

```bash
PYTHONPATH=src pytest -q
coverage run -m pytest -q
coverage report
```

Coverage threshold: `80%`.

## Notes

Snapmaker Orca Linux CLI `01.10.01.50` segfaults when a flattened U1 process profile includes `wipe_tower_filament`. V1 is single-material, so generated runtime profiles omit that multi-material field.

See `docs/` for phase notes and architecture details.