Skip to content
Back to search

mcp-orca

A safe, structured Model Context Protocol server for OrcaSlicer and FDM 3D printing G-code generation workflows.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/martinsgmx--mcp-orca/badge.svg)](/listings/martinsgmx--mcp-orca)

HTML

<a href="/listings/martinsgmx--mcp-orca"><img src="/api/listings/martinsgmx--mcp-orca/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 138 lines
  1. # mcp-orca
  2. A safe, structured [Model Context Protocol](https://modelcontextprotocol.io) server for **OrcaSlicer** and FDM 3D printing G-code generation workflows.
  3. ## Architecture (inspired by `mcp-cura`)
  4. `mcp-orca` is a new standalone Rust project inspired by the structure and ergonomics of [`mcp-cura`](https://github.com/martinsgmx/mcp-cura) (used as a reference only, not a fork/copy): similar layering around tools, engine runners, profiles, slicing/jobs, workspace, and safety.
  5. - **Runners:** host CLI and Docker. Use the built-in `engine.preset = "orca"` for the documented OrcaSlicer headless CLI, or provide `engine.slice_command` for a custom/target-specific invocation (`slice_command` always overrides the preset).
  6. - **Essentials:** slicing requires resolved **printer + filament + process** presets (no invented defaults). The `orca` preset requires those selections to resolve to native OrcaSlicer `.json` preset files (paths, indexed presets, or a workspace profile's `base_profile`).
  7. - **Profile safety:** no whole-system scans; bounded/explicit paths; backups before any in-place profile modification; custom profiles stored in the workspace.
  8. ## Build and run
  9. Requires Rust 1.89 (see `rust-toolchain.toml`).
  10. ```sh
  11. cargo build --release
  12. cargo run -- init --output mcp-orca.toml # starter config
  13. cargo run -- --config mcp-orca.toml # MCP server over stdio (default)
  14. cargo run -- --config mcp-orca.toml tools # list tools
  15. cargo run -- --config mcp-orca.toml tools --json # machine-readable catalog (risk/gate/args)
  16. cargo run -- --config mcp-orca.toml doctor # environment/diagnostics
  17. cargo run -- --config mcp-orca.toml print-config
  18. cargo run -- --config mcp-orca.toml approvals list
  19. ```
  20. Configuration precedence: built-in defaults < TOML file < `MCP_ORCA_*` environment variables < CLI flags.
  21. ## Engine configuration (slicing)
  22. Slicing stays disabled until an invocation is configured: set `engine.preset = "orca"` **or** provide `engine.slice_command`. The adapter stages inputs into the job directory, runs the slicer with timeout + cancellation, captures logs, and imports the produced G-code as an artifact.
  23. ### Built-in OrcaSlicer preset (`engine.preset = "orca"`)
  24. Uses the documented OrcaSlicer headless CLI contract (researched from the upstream wiki):
  25. - Invocation shape: staged model(s) + `--load-settings "process.json;printer.json"` + `--load-filaments filament.json` + merged setting overrides + `--arrange 1 --slice 0 --outputdir {jobdir} --export-settings {jobdir}/orca_effective_settings.json`.
  26. - **Native presets required:** `printer`/`filament`/`process` selections must resolve to real `.json` preset files (direct path, indexed/discovered preset, or a workspace custom-profile artifact whose `base_profile` points at one). Workspace profile artifacts still contribute merged setting overrides.
  27. - **Setting overrides:** merged workspace/override settings are passed as `--key=value`. OrcaSlicer CLI flags use hyphens, so setting keys are converted underscore→hyphen (`layer_height` → `--layer-height`). Booleans become `1`/`0`, arrays are comma-joined. Preset-identity, print-host, and internal extruder-bookkeeping keys that Orca excludes from CLI overrides are omitted.
  28. - **Output:** Orca writes `plate_<N>.gcode` into `--outputdir`; the preset collects results into the job's `output.gcode` artifact (single plate: renamed/copied; multi-plate: concatenated in sorted order with plate markers, while individual plate files remain in the job directory). Use a custom `slice_command` for per-plate artifact handling.
  29. - **Docker:** preset JSONs are staged into the mounted job directory so the container can read them.
  30. ```toml
  31. [engine]
  32. runner = "binary"
  33. preset = "orca"
  34. binary = "orca-slicer"
  35. # docker_image = "your-orcaslicer-image:tag"
  36. timeout_secs = 900
  37. ```
  38. ### Custom argv template (`engine.slice_command`)
  39. `slice_command` (and `docker_command`) are argv arrays expanded per job. An explicit `slice_command` overrides the preset.
  40. Placeholders: `{binary}`, `{image}`, `{jobdir}`, `{gcode}`, `{models}` (one argv entry per model), `{model}` (first model), `{printer}`, `{filament}`, `{process}`, `{project}`, `{overrides}`, `{settings}`, `{plan_json}`.
  41. Extra slicer environment variables can be set with `engine.env`; values are placeholder-expanded too:
  42. ```toml
  43. [engine]
  44. env = { ORCA_PROFILE_DIR = "{jobdir}/profiles", MCP_ORCA_JOB = "{jobdir}" }
  45. ```
  46. Example custom host template:
  47. ```toml
  48. [engine]
  49. runner = "binary"
  50. binary = "orca-slicer"
  51. slice_command = [
  52. "{binary}", "{models}",
  53. "--load-settings", "{process};{printer}",
  54. "--load-filaments", "{filament}",
  55. "--arrange", "1", "--slice", "0",
  56. "--outputdir", "{jobdir}",
  57. ]
  58. ```
  59. Example Docker configuration:
  60. ```toml
  61. [engine]
  62. runner = "docker"
  63. preset = "orca" # or provide slice_command
  64. docker_image = "your-orcaslicer-image:tag"
  65. # docker_command = ["docker", "run", "--rm", "-v", "{jobdir}:{jobdir}", "-w", "{jobdir}"]
  66. ```
  67. For Docker, the job directory is mounted by default; bind-mount any additional directories needed by a custom `slice_command`. The built-in preset stages required preset files into the job directory.
  68. ## Safety, approvals, and audit
  69. Every tool call goes through one registry choke point: policy evaluation, optional approval, execution, and an audit record.
  70. - Policy (`[policy]`) allows a read-only mode and per-capability flags for workspace writes, slicing, export, and delete.
  71. - `orca_artifact_export`, `orca_artifact_delete`, and other gated actions do not execute on the first attempt. They create a pending approval request and return its id.
  72. - List requests with `orca_pending_approvals`, then approve or deny with `orca_approval_decide` (`approval.mode = "in_band"` or `"both"`). Retry the **identical** call within `approval.ttl_secs`; the approval is consumed exactly once.
  73. - With `approval.mode = "out_of_band"`, MCP-side decisions are refused. Decide from the host instead: `mcp-orca approvals list`, `mcp-orca approvals approve <apr_id>`, `mcp-orca approvals deny <apr_id>`.
  74. - Audit records are appended as JSONL to `<workspace>/audit.jsonl` (tool, timestamp, outcome, short sanitized detail). Secrets are never written.
  75. ## Tools
  76. Admin/approvals: `orca_server_info`, `orca_engine_info`, `orca_policy_info`, `orca_pending_approvals`, `orca_approval_decide`, `orca_doctor`.
  77. Artifacts: `orca_artifact_import`, `orca_artifact_list`, `orca_artifact_get`, `orca_artifact_read_text`, `orca_artifact_export`, `orca_artifact_delete`.
  78. Mesh: `orca_mesh_inspect` (STL + OBJ), `orca_mesh_transform` (translate/rotate/scale/mirror; STL or OBJ in, binary STL out), `orca_mesh_merge` (STL/OBJ in, binary STL out).
  79. Profiles: `orca_profile_list`, `orca_profile_get` (discovered entries + workspace artifacts), `orca_profile_refresh`, `orca_profile_resolve` (merged effective settings), `orca_profile_create`, `orca_profile_update` (new content-addressed version).
  80. Slicing/jobs: `orca_slice`, `orca_slice_status`, `orca_slice_wait`, `orca_slice_cancel`, `orca_slice_list`.
  81. G-code: `orca_gcode_inspect`.
  82. ## Tests
  83. ```sh
  84. cargo test
  85. cargo clippy --all-targets
  86. ./scripts/smoke.sh # fmt-adjacent checks: tests, clippy, tools, doctor, stdio handshake
  87. ./scripts/http_smoke.sh # token-gated HTTP: 401 without token, 200 with token
  88. ```
  89. The integration suite uses fake host/Docker slicer scripts to exercise the full import → mesh → slice → G-code artifact path without OrcaSlicer installed, plus approval, profile-resolution, and mesh (STL/OBJ) flows.
  90. ## Documentation
  91. - [Design spec (v1)](docs/DESIGN.md)
  92. - [Glossary](GLOSSARY.md)
  93. - [Scripts](scripts/README.md)
  94. ## License
  95. Apache-2.0 — © 2026 Martin Sg. See [LICENSE](LICENSE).
  96. > OrcaSlicer is a separate project with its own license; `mcp-orca` invokes it as an external tool.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.